# Objective
1. "What you expected to happen" and "what actually happened" often involves trivial duplication.
2. "Please provide full reproduction steps" is not helpful advice to new contributors.
3. The OS field was commonly useless or inadequate.
4. The description for "additional information" effectively just repeated the title of the field.
## Solution
1. Unify these fields into a single "what went wrong" field.
2. Provide an example of a useful reproduction.
3. Replace OS field with an optional "Setup Information" field that captures information about other critical setup like Rust version and hardware.
4. Provide helpful advice about what sort of information may be useful to add.
The existing issue templates don't fit well for "the docs are not very good" and are too high friction.
This is intended as a very-low friction tool to provide the basis for more thorough docs PRs.
I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo.
The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md
Rules I didn't follow/fix:
* MD024/no-duplicate-heading
* Changelog: Here Heading will always repeat.
* Examples Readme: Platform-specific documentation should be symmetrical.
* MD025/single-title
* MD026/no-trailing-punctuation
* Caused by the ! in "Hello, World!".
* MD033/no-inline-html
* The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much.
* ~~MD036/no-emphasis-as-heading:~~
* ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~
* ~~MD041/first-line-heading~~
* ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~
---
I also sorted the Examples in the Readme and Cargo.toml in this order/Priority:
* Topic/Folder
* Introductionary Examples
* Alphabetical Order
The explanation for each case, where it isn't Alphabetical :
* Diagnostics
* log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own.
* ECS (Entity Component System)
* ecs_guide: The guide should be read, before diving into other Features.
* Reflection
* reflection: Basic Explanation should be read, before more advanced Topics.
* WASM Examples
* hello_wasm: It's "Hello, World!".
