Finished first version of bug report guide

docs/bug-report/index.md

@@ -1,51 +1,50 @@
 # Bug reporting
 
 Material for MkDocs is an actively maintained project that we constantly strive
-to improve. With a project of this size and complexity, :material-bug: bugs may
+to improve. With a project of this size and complexity, bugs may occur. If you
-occur. If you think you have discovered a bug, you can help us by reporting an
+think you have discovered a bug, you can help us by submitting an issue in our
-issue in our public [issue tracker].
+public [issue tracker].
 
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
 
 ## Before creating an issue
 
-With more than 20.000 users, issues are raised almost every 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. High quality and complete bug reports enable us
+fixing bugs as fast as possible. By following this guide, you will know exactly
-to help you much faster.
+what information we need to help you quickly.
 
-__Please make sure to try the following things before creating an issue__.
+__But first, please try the following things before creating an issue.__
 
 ### Upgrade to latest version
 
 Chances are, that the bug you discovered was already fixed in a subsequent
-version. Thus, before reporting an issue, please ensure that you're running the
+version. Thus, before reporting an issue, ensure that you're running the
 [latest version] of Material for MkDocs. Please consult our [upgrade guide] to
 learn how to upgrade to the latest version.
 
 !!! warning "Bug fixes are not backported"
 
-    Please understand that only issues that occur in the latest version of
+    Please understand that only bugs that occur in the latest version of
     Material for MkDocs will be addressed. Also, in order to reduce duplicate
-    efforts, fixes are not backported to earlier versions.
+    efforts, fixes cannot be backported to earlier versions.
 
 ### Remove customizations
 
-If you're using [customizations] like [additional CSS] and [JavaScript], or
+If you're using [customizations] like [additional CSS], [JavaScript], or
 [theme extension], please remove them from `mkdocs.yml` before reporting a bug.
-__We can't offer official support for bugs that might hide in your overrides__,
+We can't offer official support for bugs that might hide in your overrides, so
-so please remove the following settings from `mkdocs.yml`:
+make sure to omit the following settings from `mkdocs.yml`:
 
   - [`theme.custom_dir`][theme.custom_dir]
   - [`theme.hooks`][theme.hooks]
   - [`extra_css`][extra_css]
   - [`extra_javascript`][extra_javascript]
 
-If after removing those settings, the bug is gone, the bug is likely caused by
+If, after removing those settings, the bug is gone, the bug is likely caused by
 your customizations. A good idea is to add them back gradually to narrow down
-the root cause. Don't be shy to ask on our [discussion board] or
+the root cause of the problem. If you did a major version upgrade, make sure you
-[:simple-stackoverflow: StackOverflow][StackOverflow] for help if you're running
+adjusted all partials you have overridden.
-into problems.
 
 !!! warning "Customizations mentioned in our documentation"
 
@@ -54,6 +53,9 @@ into problems.
     our documentation explicitly mentions], you are of course encouraged to
     report it.
 
+__Don't be shy to ask on our [discussion board] for help if you run into
+problems.__
+
   [latest version]: ../changelog/index.md
   [upgrade guide]: ../upgrade.md
   [Customizations]: ../customization.md
@@ -70,10 +72,50 @@ into problems.
 
 ### Search for solutions
 
-TBD
+At this stage, we know that the problem persists in the latest version and is
+not caused by any of your customizations. However, it's possible that the issue
+might be the result of a small typo or a syntactical error in a configuration
+file, e.g. `mkdocs.yml`.
 
-- Documentation
+Now, before you go through the trouble of creating a bug report, that we
-- Open issues
+maintainers close right away with a link to the relevant documentation section
+or another already reported or closed issue or discussion, you can save time for
+us and yourself by doing some research:
+
+1.  [Search our documentation] and look for the relevant sections that might
+    possibly be related to your problem. If found, make sure that you configured
+    everything correctly.[^1]
+
+  [^1]:
+    When adding lines to `mkdocs.yml`, make sure you are preserving the
+    indentation as mentioned in the documentation, since YAML is a
+    whitespace-sensitive language. Many reported issues turn out to be
+    configuration errors.
+
+2.  [Search our issue tracker][issue tracker], as another user might already
+    have reported the same problem, and there might even be a known workaround
+    or fix for it. Thus, no need to create a new issue.
+
+3.  [Search our discussion board][discussion board] to learn if other users
+    are struggeling with similar problems, and work together with our
+    great community towards a solution. Many problems are solved here.
+
+__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
+them in the bug report.__[^2]
+
+  [^2]:
+    We might be using terminology in our documentation different from yours,
+    but mean the same. When you include the search terms and related links
+    in your bug report, you help us to adjust and improve the documentation.
+
+---
+
+At this point, when you still haven't found a solution to your problem, we
+encourage you to create an issue, because it's now very likely that you
+stumbled over something we don't know yet. Read the next section to learn
+how to create a complete and helpful bug report.
+
+  [Search our documentation]: ?q=
 
 ## Issue template
 
@@ -108,7 +150,7 @@ can be inferred from the title.
 
 | <!-- --> | Example  |
 | -------- | -------- | 
-| :material-check:{ style="color: #4DB6AC" } __Good__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
 | :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
 | :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
 | :material-close:{ style="color: #EF5350" } __Generic__ | Please help
@@ -117,8 +159,8 @@ can be inferred from the title.
 
 Before describing the bug, you can provide additional context that can be
 helpful to understand what you were trying to achieve. Explain the circumstances
-in which you're using Material for MkDocs. Don't write about the bug itself or
+in which you're using Material for MkDocs, and what you _think_ might be
-anything related.
+relevant. Don't write about the bug here.
 
 > __Why this might be helpful__: some errors only manifest in specific settings,
 > environments or edge cases, for example when your documentation contains
@@ -129,25 +171,25 @@ anything related.
 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
 that should be reported to Material for MkDocs, and not to one of its
-[dependencies]. Guideline for descriptions:
+[dependencies]. Adhere to the following principles:
 
 -   __Explain the <u>what</u>, not the <u>how</u>__ – don't explain
     [how to reproduce the bug][Steps to reproduce] here, we're getting there.
     Focus on articulating the problem and its impact as clearly as possible.
 
 -   __Keep it short and concise__ – if the bug can be precisely explained in one
-    or two sentences, perfect. Don't inflate it – the maintainers and users
+    or two sentences, perfect. Don't inflate it – maintainers and future users
-    reading your words will be grateful.
+    will be grateful, having to read less.
 
--   __One :material-bug: bug at a time__ – if you encountered several unreleated
+-   __One bug at a time__ – if you encountered several unrelated bugs, please
-    bugs, please open an issue for each of them. Don't report them all in the
+    create separate issues for them. Don't report them in the same issue, as
-    same issue, as this makes communication difficult.
+    this makes attribution difficult.
 
 ---
 
-__Stretch :material-run-fast: goal__ – if you found a workaround or a way to fix
+:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix
 the bug, you can help other users to temporarily mitigate the problem before
-Material for MkDocs fixes the bug in its code base.
+we maintainers can fix the bug in our code base.
 
 > __Why we need this__: in order for us to understand the issue at hand, we
 > need a clear description of the problem and its impact, which is essential
@@ -157,42 +199,105 @@ Material for MkDocs fixes the bug in its code base.
 
 ### Related links
 
-Of course, prior to reporting a bug, you have read our documentation and could
+Of course, prior to reporting a bug, you have read our documentation and
-not find a working solution. Please share links to all sections of our
+[could not find a working solution][search for solutions]. Please share links
-documentation that might be relevant to the bug, as it helps us gradually
+to all sections of our documentation that might be relevant to the bug, as it
-improve it.
+helps us gradually improve it.
 
 Additionally, since you have searched our [issue tracker] and [discussion board]
 before reporting an issue, and have possibly found several issues or
 discussions, include those as well. Every link to an issue or discussion creates
-a backlink, guiding us maintainers and future users.
+a backlink, guiding us maintainers and other users in the future.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you also include the search terms you
+used when [searching for a solution][search for solutions] to your problem, you
+make it easier for us maintainers to improve the documentation.
 
 > __Why we need this__: related links help us better understand what you were
 > trying to achieve and whether sections of our documentation need to be
 > adjusted, extended or overhauled.
 
+  [search for solutions]: #search-for-solutions
+
 ### Reproduction
 
-TBD
+A minimal reproduction is at the heart of every well-written bug report, as
+it allows us maintainers to quickly recreate the necessary conditions to inspect
+the bug and quickly find its root cause. It's 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 }
+
+---
+
+After you created the reproduction, you should have a .zip file, ideally not
+larger than 1 MB. Just drag and drop the .zip file into this field, which will
+automatically upload it to GitHub.
+
+> __Why we need this__: if an issue contains no minimal reproduction, or just
+> a link to a repositority with thousands of files, the maintainers would need
+> to invest a lot of time into trying to recreate the right conditions to even
+> inspect the bug, let alone fix it.
+
+!!! warning "Don't share links to repositories"
+
+    While we know that it is good practice among developers to include a link
+    to a repository with the bug report, we currently don't support those in our
+    process. The reason is that the reproduction that is automatically
+    produced by the [built-in info plugin] contains all of the necessary
+    environment information that is often forgotten to be included.
+    
+    Additionally, there are many non-technical users of Material for MkDocs that
+    have trouble creating repositories.
+
+  [Create reproduction]: reproduction.md
+  [built-in info plugin]: reproduction.md#built-in-info-plugin
 
 ### Steps to reproduce
 
-TBD
+At this point, you provided us with enough information to understand the bug,
+and you gave us a reproduction that we can run and inspect. However, when we
+run your reproduction, it might not be immediately apparent how we can see
+the bug in action.
+
+Next, please list the specific steps we should follow when running your
+reproduction to observe the bug. Keep the steps short and concise and make sure
+to not leave anything out. Use simple language as you would explain it to a five
+year old and focus on continuity.
+
+> __Why we need this__: we must know how to navigate your reproduction in order
+> to observe the bug, as some bugs only occur at certain viewports or in
+> specific conditions.
 
 ### Browser <small>optional</small> { #browser }
 
-TBD
+If you're reporting a bug that only happens in one or more _specific_ browsers,
+we need to know which browsers are affected. This field is optional, as it is
+only relevant when the bug you are reporting does not involve a crash when
+[previewing] or [building] your site.
+
+> __Why we need this__: some bugs only occur in specific browsers or versions.
+> Since now, almost all browser are evergreen, we usually don't need to know the
+> version in which it occurs, but we might ask for it later. When in doubt, add
+> the browser version as the first step in the field above.
+
+  [previewing]: http://localhost:8000/mkdocs-material/creating-your-site/#previewing-as-you-write
+  [building]: http://localhost:8000/mkdocs-material/creating-your-site/#building-your-site
 
 ### Checklist
 
-TBD
+Thanks for following the guide, and creating a high quality and complete bug
+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 everything we need to
+know to help you.
 
-## General
+__We'll take it from here.__
-
-### Dependencies
-
-TBD
 
 ## Incomplete issues
 
-TBD
+Please understand, that we reserve us the right to close incomplete issues which
+do not contain minimal reproductions, or do not adhere to the quality standards
+and requirements mentioned in this document. We will try our best to help you
+improve your bug report in the comments.

docs/reference/buttons.md

@@ -1,5 +1,5 @@
 ---
-icon: material/gesture-tap-button
+icon: material/button-cursor
 ---
 
 # Buttons

mkdocs.yml

@@ -168,7 +168,7 @@ nav:
     - License: license.md
     - Bug reporting:
       - bug-report/index.md
-      - How to create a reproduction: bug-report/reproduction.md
+      - Creating a reproduction: bug-report/reproduction.md
     - Changelog:
       - changelog/index.md
       - How to upgrade: upgrade.md