2023-01-29 19:14:23 +01:00
|
|
|
|
# Reporting a docs issue
|
|
|
|
|
|
|
|
|
|
|
|
In the past 7 years, our documentation has grown to more than 60 pages. With a
|
|
|
|
|
|
site being this large, inconsistencies can occur. If you found an inconsistency
|
|
|
|
|
|
or see room for clarification or improvement, please submit an issue to
|
|
|
|
|
|
our public [issue tracker] by following this guide.
|
|
|
|
|
|
|
|
|
|
|
|
[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 the following 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
|
|
|
|
|
|
the issue tracker.
|
|
|
|
|
|
|
|
|
|
|
|
| <!-- --> | Example |
|
|
|
|
|
|
| -------- | -------- |
|
2023-01-29 22:57:53 +01:00
|
|
|
|
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
|
2023-01-29 19:14:23 +01:00
|
|
|
|
| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
|
|
|
|
|
|
| :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. Maintainers and
|
|
|
|
|
|
future users will be grateful for having to read less.
|
|
|
|
|
|
|
|
|
|
|
|
- __One issue at a time__ – if you encountered 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__: in order for us to understand the problem, we need a
|
|
|
|
|
|
> clear description of it and quantify its impact, which is essential for triage
|
|
|
|
|
|
> and prioritization.
|
|
|
|
|
|
|
|
|
|
|
|
### 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__: 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 creating a high-quality and complete issue
|
|
|
|
|
|
report – you are almost done. This section 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 our documentation.
|
|
|
|
|
|
|
|
|
|
|
|
__We'll take it from here.__
|
