mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-23 21:04:56 +01:00
92 lines
3.5 KiB
Markdown
92 lines
3.5 KiB
Markdown
# Documentation issues
|
||
|
||
Our documentation is composed of more than 80 pages and includes extensive
|
||
information on features, configurations, customizations, and much more. If you
|
||
have found an inconsistency or see room for improvement, please follow this
|
||
guide to submit an issue on our [issue tracker].
|
||
|
||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||
|
||
## Issue template
|
||
|
||
Reporting a documentation issue is usually less involved than reporting a bug,
|
||
as we don't need a [reproduction]. Please thoroughly read this guide before
|
||
creating a new documentation issue, and provide the following information as
|
||
part of the issue:
|
||
|
||
- [Title]
|
||
- [Description]
|
||
- [Related links]
|
||
- [Proposed change] <small>optional</small>
|
||
- [Checklist]
|
||
|
||
[reproduction]: ../guides/creating-a-reproduction.md
|
||
[Title]: #title
|
||
[Description]: #description
|
||
[Related links]: #related-links
|
||
[Proposed change]: #proposed-change
|
||
[Checklist]: #checklist
|
||
|
||
### Title
|
||
|
||
A good title should be a short, one-sentence description of the issue, contain
|
||
all relevant information and, in particular, keywords to simplify the search in
|
||
our issue tracker.
|
||
|
||
| <!-- --> | Example |
|
||
| -------- | -------- |
|
||
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
|
||
| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
|
||
| :material-close:{ style="color: #EF5350" } __Useless__ | 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. Maintainers and future
|
||
users will be grateful for having to read less.
|
||
|
||
- __One issue at a time__ – if you encounter several unrelated inconsistencies,
|
||
please create separate issues for them. Don't report them in the same issue
|
||
– it makes attribution difficult.
|
||
|
||
> __Why we need this__: describing the problem clearly and concisely is a
|
||
> prerequisite for improving our documentation – we need to understand what's
|
||
> wrong, so we can fix it.
|
||
|
||
### Related links
|
||
|
||
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 and
|
||
other possibly related sections. Make sure to use anchor links (permanent links)
|
||
where possible, as it simplifies discovery.
|
||
|
||
> __Why we need this__: providing the links to the documentation help us
|
||
> understand which sections of our documentation need to be adjusted, extended,
|
||
> or overhauled.
|
||
|
||
|
||
### Proposed change <small>optional</small> { #proposed-change }
|
||
|
||
Now that you have provided us with the description and links to the
|
||
documentation sections, you can help us, maintainers, and the community by
|
||
proposing an improvement. You can sketch out rough ideas or write a concrete
|
||
proposal. This field is optional but very helpful.
|
||
|
||
> __Why we need this__: an improvement proposal can be beneficial for other
|
||
> users who encounter the same issue, as they offer solutions before we
|
||
> maintainers can update the documentation.
|
||
|
||
### Checklist
|
||
|
||
Thanks for following the guide and providing valuable feedback for our
|
||
documentation – you are almost done. 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 it.
|
||
|
||
__We'll take it from here.__
|