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 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¶
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 | |
|---|---|
| Clear | Clarify social cards setup on Windows |
| Unclear | Missing information in the docs |
| 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 optional¶
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.