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 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 optional
• 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.

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 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: 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.