Updated documentation and change request template

docs/contributing/index.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Material for MkDocs is an actively maintained and constantly improved project 
+that caters to a diverse user base with varying backgrounds and needs. In order
+to effectively address the needs of all our users, evaluate requests, and fix 
+bugs, a lot of work from us maintainers is required.
+
+## How to contribute
+
+We have invested quite a lot of time in creating better templates for our
+[issue tracker], optimizing the processes for our users to report bugs, request
+features or changes, contribute to the project or exchange with our community. This section of
+the documentation explains each process.
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+### Creating an issue
+
+<div class="grid cards" markdown>
+
+-   :material-bug:{ .lg .middle } __Something is not working?__
+
+    ---
+
+    Report a bug in Material for MkDocs by creating an issue and a reproduction
+
+    [:octicons-arrow-right-24: Report a bug][report a bug]
+
+-   :material-file-document:{ .lg .middle } __Missing information in our docs?__
+
+    ---
+
+    Report missing information or potential inconsistencies in our documentation
+
+    [:octicons-arrow-right-24: Report a docs issue][report a docs issue]
+
+-   :material-lightbulb-on:{ .lg .middle } __Want to submit an idea?__
+
+    ---
+
+    Propose a change or feature request or suggest an improvement
+
+    [:octicons-arrow-right-24: Request a change][request a change]
+
+-   :material-chat-question:{ .lg .middle } __Have a question or need help?__
+
+    ---
+
+    Ask questions on our discussion board and get in touch with our community
+
+    [:octicons-arrow-right-24: Ask as question][ask a question]
+
+</div>
+
+  [report a bug]: reporting-a-bug.md
+  [report a docs issue]: reporting-a-docs-issue.md
+  [request a change]: requesting-a-change.md
+  [ask a question]: https://github.com/squidfunk/mkdocs-material/discussions

docs/contributing/reporting-a-bug.md

@@ -1,15 +1,15 @@
-# Bug reporting
+# Reporting a bug
 
 Material for MkDocs is an actively maintained project that we constantly strive
 to improve. With a project of this size and complexity, bugs may occur. If you
 think you have discovered a bug, you can help us by submitting an issue in our
-public [issue tracker], following this guide.
+public [issue tracker] by following this guide.
 
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
 
 ## Before creating an issue
 
-With more than 20.000 users, issues are created every other day. The maintainers
+With more than 20,000 users, issues are created every other day. The maintainers
 of this project are trying very hard to keep the number of open issues down by
 fixing bugs as fast as possible. By following this guide, you will know exactly
 what information we need to help you quickly.
@@ -118,14 +118,14 @@ how to create a complete and helpful bug report.
 
 ## Issue template
 
-We have created a new issue template to make the bug-reporting process as simple
+We have created a new issue template to make the bug reporting process as simple
 as possible and more efficient for the community and us. It is the result of
 our experience answering and fixing more than 1,600 issues (and counting) and
 consists of the following parts:
 
 - [Title]
 - [Context] <small>optional</small>
-- [Bug description]
+- [Description]
 - [Related links]
 - [Reproduction]
 - [Steps to reproduce]
@@ -134,7 +134,7 @@ consists of the following parts:
 
   [Title]: #title
   [Context]: #context
-  [Bug description]: #bug-description
+  [Description]: #description
   [Related links]: #related-links
   [Reproduction]: #reproduction
   [Steps to reproduce]: #steps-to-reproduce
@@ -157,7 +157,7 @@ can be inferred from the title.
 ### Context <small>optional</small> { #context }
 
 Before describing the bug, you can provide additional context for us to
-understand what you were trying to achieve. Explain the circumstances
+understand what you are trying to achieve. Explain the circumstances
 in which you're using Material for MkDocs, and what you _think_ might be
 relevant. Don't write about the bug here.
 
@@ -165,7 +165,7 @@ relevant. Don't write about the bug here.
 > environments or edge cases, for example, when your documentation contains
 > thousands of documents.
 
-### Bug description
+### Description
 
 Now, to the bug, you want to report. Provide a clear, focused, specific, and
 concise summary of the bug you encountered. Explain why you think this is a bug
@@ -239,7 +239,7 @@ it allows us maintainers to quickly recreate the necessary conditions to inspect
 the bug and quickly find its root cause. It's a proven fact that issues with
 concise and small reproductions can be fixed much faster.
 
-[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
+[:material-bug:&nbsp; Create a reproduction][Create reproduction]{ .md-button .md-button--primary }
 
 ---
 
@@ -263,8 +263,8 @@ automatically upload it to GitHub.
     Additionally, there are many non-technical users of Material for MkDocs that
     have trouble creating repositories.
 
-  [Create reproduction]: reproduction.md
+  [Create reproduction]: ../guides/creating-a-reproduction.md
-  [built-in info plugin]: reproduction.md#creating-a-zip-file
+  [built-in info plugin]: ../guides/creating-a-reproduction.md#creating-a-zip-file
 
 ### Steps to reproduce
 

docs/contributing/reporting-a-docs-issue.md

@@ -0,0 +1,89 @@
+# 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  |
+| -------- | -------- | 
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify how to set up social cards 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 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.__

docs/contributing/requesting-a-change.md

@@ -0,0 +1,204 @@
+# Requesting a change
+
+Material for MkDocs is a powerful tool to create beautiful and functional
+project documentation. With more than 20,000 users, we understand that our
+project serves a wide range of use cases, which is why we have created the
+following guide.
+
+---
+
+Put yourself in our shoes – with a project of this size, it can be challenging
+to maintain existing functionality while constantly adding new features at the
+same time. We highly value every idea or contribution from our community, and
+we kindly ask you to take the time to read the following guidelines before 
+submitting your change request in our public [issue tracker]. This will help us 
+better understand the proposed change, and how it will benefit the community.
+
+This guide is our best effort to explain the criteria and reasoning behind our
+decisions when evaluating change requests and considering them for
+implementation. 
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Before creating an issue
+
+Before you invest your time to fill out and submit a change request, we kindly
+ask you to do some preliminary work by answering some questions to determine if
+your idea is a good fit for Material for MkDocs and matches the project's
+[philosophy] and tone.
+
+__Please find answers to the following questions before creating an issue.__
+
+  [philosophy]: ../philosophy.md
+
+### It's not a bug, it's a feature
+
+Change requests are intended for suggesting minor adjustments, ideas for new
+features, or to influence the project's direction and vision. It is important
+to note that change requests are not intended for reporting bugs, as they're
+missing essential information for debugging.
+
+If you want to report a bug, please refer to our [bug reporting guide] instead.
+
+  [bug reporting guide]: reporting-a-bug.md
+
+### Source of inspiration
+
+If you have seen your idea implemented in another static site generator or
+theme, make sure to collect enough information on its implementation before
+submitting, as this allows us to evaluate potential fit more quickly. Explain
+what you like and dislike about the implementation.
+
+### Benefit for the community
+
+Our [discussion board] is the best place to connect with our community. When 
+evaluating new ideas, it's essential to seek input from other users and consider 
+alternative viewpoints. This approach helps to implement new features in a way
+that benefits a large number of users.
+
+[:octicons-comment-discussion-16:  Start a discussion][Start a discussion]{ .md-button .md-button--primary }
+
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+  [Start a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+
+## Issue template
+
+Now that you have taken the time to do the necessary preliminary work and ensure 
+that your idea meets our requirements, you are invited to create a change
+request. The following guide will walk you through all necessary steps to help
+you submit a comprehensive and useful issue:
+
+- [Title]
+- [Context] <small>optional</small>
+- [Description]
+- [Related links]
+- [Use cases]
+- [Visuals] <small>optional</small>
+- [Checklist]
+
+  [Title]: #title
+  [Context]: #context
+  [Description]: #description
+  [Related links]: #related-links
+  [Use cases]: #use-cases
+  [Visuals]: #visuals
+  [Checklist]: #checklist
+
+### Title
+
+A good title is short and descriptive. It should be a one-sentence executive
+summary of the idea, so the potential impact and benefit for the community can 
+be inferred from the title.
+
+| <!-- --> | Example  |
+| -------- | -------- | 
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
+| :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
+| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+
+### Context <small>optional</small> { #context }
+
+Before describing your idea, you can provide additional context for us to
+understand what you are trying to achieve. Explain the circumstances
+in which you're using Material for MkDocs, and what you _think_ might be
+relevant. Don't write about the change request here.
+
+> __Why this might be helpful__: some ideas might only benefit specific
+> settings, environments or edge cases, for example, when your documentation
+> contains thousands of documents. With a little context, change requests
+> can be prioritized more accurately.
+
+### Description
+
+Next, provide a detailed and clear description of your idea. Explain why your 
+idea is relevant to Material for MkDocs and must be implemented here, and not
+in one of its dependencies:[^1]
+
+  [^1]:
+    Sometimes, users suggest ideas on our [issue tracker] that concern one of
+    our upstream dependencies, including [MkDocs], [Python Markdown],
+    [Python Markdown Extensions] or third-party plugins. It's a good idea to
+    think about whether your idea is beneficial to other themes, upstreaming
+    change requests for bigger impact.
+
+-   __Explain the <u>what</u>, not the <u>why</u>__ – don't explain
+    [the benefits of your idea][Use cases] here, we're getting there.
+    Focus on describing the proposed change request as precisely as possible.
+
+-   __Keep it short and concise__ – be brief and to the point when describing 
+    your idea, there is no need to over-describe it. Maintainers and future
+    users will be grateful for having to read less.
+
+-   __One idea at a time__ – if you have multiple ideas that don't belong 
+together, please open separate change requests for each of those ideas.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you have a customization or another
+way to add the proposed change, you can help other users by sharing it here
+before we  maintainers can add it to our code base.
+
+> __Why we need this__: To understand and evaluate your proposed change, we
+> need to have a clear understanding of your idea. By providing a detailed and 
+> precise description, you can help save you and us time spent discussing
+> further clarification of your idea in the comments.
+
+  [MkDocs]: https://www.mkdocs.org
+  [Python Markdown]: https://python-markdown.github.io/extensions/
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+  [theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
+
+### Related links
+
+Please provide any relevant links to issues, discussions, or documentation 
+sections related to your change request. If you (or someone else) already
+discussed this idea with the community on our discussion board, please include 
+the link to the discussion as well.
+
+> __Why we need this__: Related links help us gain a comprehensive
+> understanding of your change request by providing additional context.
+> Additionally, linking to previous issues and discussions allows us
+> to quickly evaluate the feedback and input already provided by the community.
+
+### Use cases
+
+Explain how your change request would work from an author's and user's
+perspective – what's the expected impact and why does it not only benefit you,
+but other users? How many of them? Furthermore, would it potentially break
+existing functionality?
+
+> __Why we need this__: Understanding the use cases and benefits of an idea is 
+> crucial in evaluating its potential impact and usefulness for the project and 
+> its users. This information helps us to understand the expected value of the 
+> idea and how it aligns with the goals of the project.
+
+### Visuals <small>optional</small> { #visuals }
+
+We now have a clear and detailed description of your idea, including information 
+on its potential use cases and relevant links for context. If you have any 
+visuals, such as sketches, screenshots, mockups, or external assets, you may 
+present them in this section.
+
+__You can drag and drop the files here or include links to external assets.__
+
+Additionally, if you have seen this change, feature, or improvement used in 
+other static site generators or themes, please provide an example by showcasing 
+it and describing how it was implemented and incorporated.
+
+> __Why we need this__: Illustrations and visuals can help us maintainers 
+> better understand and envision your idea. Screenshots, sketches, or mockups 
+> can create an additional level of detail and clarity that text alone may not 
+> be able to convey. Also, seeing how your idea has been implemented in other 
+> projects can help us understand its potential impact and feasibility in 
+> Material for MkDocs, which helps us maintainers evaluate and triage 
+> change requests.
+
+### Checklist
+
+Thanks for following the change request guide and creating a high-quality 
+change request. This section ensures that you have read this guide and have
+worked to your best knowledge to provide us with every piece of information to 
+review your idea for Material for MkDocs.
+
+__We'll take it from here.__

docs/guides/creating-a-reproduction.md

@@ -77,7 +77,7 @@ inside it. Next:
     means that the bug does not occur when they are omitted. Remove all
     non-essential lines and files.
 
-  [bug reporting guide]: index.md#upgrade-to-latest-version
+  [bug reporting guide]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
   [minimal configuration]: ../../creating-your-site/#minimal-configuration
 
 ### Creating a .zip file

mkdocs.yml

@@ -161,12 +161,17 @@ nav:
     - Philosophy: philosophy.md
     - Alternatives: alternatives.md
     - License: license.md
-    - Bug reporting:
-      - bug-report/index.md
-      - Creating a reproduction: bug-report/reproduction.md
     - Changelog:
       - changelog/index.md
       - How to upgrade: upgrade.md
+    - Contributing:
+      - contributing/index.md
+      - Reporting a bug: contributing/reporting-a-bug.md
+      - Reporting a docs issue: contributing/reporting-a-docs-issue.md
+      - Requesting a change: contributing/requesting-a-change.md
+      - Asking a question: https://github.com/squidfunk/mkdocs-material/discussions
+    - Guides:
+      - Creating a reproduction: guides/creating-a-reproduction.md
   - Setup:
     - Changing the colors: setup/changing-the-colors.md
     - Changing the fonts: setup/changing-the-fonts.md