1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-22 20:36:02 +01:00
mkdocs-material/docs/contributing/reporting-a-docs-issue.md
2023-04-11 14:30:56 +02:00

90 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Reporting a docs issue
In the past seven years, our documentation has grown to more than 60 pages. With
a site being this large, inconsistencies can occur. If you find 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 |
| -------- | -------- |
| :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" } __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 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__: 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 the best of your knowledge to provide us with every piece of
information we need to improve our documentation.
__We'll take it from here.__