mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# Documentation issue reporting
|
||
|
||
The documentation for Material for MkDocs is spread across more than 60 pages
|
||
and covers information about its features, configurations, and everything you
|
||
need to take advantage of Material for MkDocs' full capabilities. If you have
|
||
found an inconsistency, an issue, or see room for improvement in the
|
||
documentation, please submit an issue to our public [issue tracker] by following
|
||
this guide.
|
||
|
||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||
|
||
## Documentation issue template
|
||
|
||
Reporting something in the documentation differs from reporting a bug in the code.
|
||
Please thoroughly read the following guide before creating a new documentation
|
||
issue.
|
||
|
||
### Title
|
||
|
||
An excellent documentation issue title should be a short, one-sentence
|
||
description of the issue and contain all relevant information and, in particular
|
||
keywords – to simplify the search in the issue tracker.
|
||
|
||
| <!-- --> | Example |
|
||
| -------- | -------- |
|
||
| :material-check:{ style="color: #4DB6AC" } __Clear__ | wrong feature flag code.action
|
||
| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information
|
||
| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
|
||
|
||
### Description
|
||
|
||
Provide a clear and concise summary of the inconsistency or issue you
|
||
encountered in the documentation or the documentation section that needs
|
||
improvement. Explain why you think the documentation should be adjusted and
|
||
describe the severity of the issue.
|
||
|
||
- __Keep it short and concise__ – if the inconsistency or issue can be
|
||
precisely explained in one or two sentences, perfect.
|
||
|
||
- __One issue at a time__ – if you encounter multiple unrelated inconsistencies
|
||
or issues on different documentation sites, please create separate issues.
|
||
Don't report multiple issues in one issue report, which makes identifying
|
||
them difficult.
|
||
|
||
> __Why we need this__: for us to understand the issue you have found or the
|
||
> clarification of the documentation needs, we ask for a description and
|
||
> explanation of the serenity.
|
||
|
||
### Links to the documentation
|
||
|
||
After you described the documentation section that needs to be adjusted above,
|
||
we now ask you to share the link to this specific documentation section. Make
|
||
sure you link to the sub-pages and anchor the headings directly.
|
||
|
||
> __Why we need this__: providing the link to the documentation helps us
|
||
> understand which sections of our documentation need to be adjusted, extended,
|
||
> or overhauled.
|
||
|
||
### Improvement proposals
|
||
|
||
Now that you have provided us with the description and link to the
|
||
documentation, you can help us, maintainers, and the community by proposing an
|
||
improvement. This can be a suggestion, a fix, or a temporary workaround.
|
||
|
||
> __Why we need this__: improvement proposal can be beneficial for other users
|
||
> who encounter the same issue, since it will offer them a temporary solution
|
||
> until we maintainers can update the documentation.
|
||
|
||
### Checklist
|
||
|
||
Thanks for following the documentation issue reporting guide and creating a
|
||
high-quality documentation issue report. The checklist ensures that you have read
|
||
this guide and have worked to your best knowledge to provide us with every piece
|
||
of information we need to improve the Material for MkDocs documentation.
|
||
|
||
__We'll take it from here.__
|