Document Style Guide Needed

Why Documentation Is Better With a Style Guide

Disambiguate Multiple Solutions

Presently, all documents may be reviewed at will by the community. This is not an issue. However, as a result of the lack of style guide and varying opinions of reviewers, the reviews are only based off of opinion. These solely opinion reviews are difficult to accept even when addressing issues with pull requests, as there are no hard or soft correctness rules.

The crux of the issue is any solution posed in a review has an equally valid alternative and any problem raised has multiple solutions. To prevent unneeded delays caused by selecting valid solutions a style guide is required.

#358 is one of the latest closures that can be attributed to style confusions.

Improve the Reading Experience

Access to the content can be improved. Consistent document formatting and vocabulary reduces the time that a reader needs to comprehend said document.

Reduce Required Writing Level

Removing or reducing the stylistic variable will improve the ability of early and non-native English writers. A well written style guide outlines what is required of a writer. If a writer follows a formula to crate a stylistically correct document, then the writer is only concerned with the content of their work rather than focusing on superfluous details.

Allow for Revision

The current state of documentation will be improved. Without a style guide readers can tell that documents have issues, but cannot pinpoint how these issue should be solved. When a style guide is applied to old work both the issues with the work and the solution to that work will be clear.

Revisions based only off of opinion will become less common. Once a document no longer contradicts the style guide there is little reason to edit it.

What Is Required?

This will need to be up to the community, but should address several key points not limited to the ones below. Ideally one canonical solution can be selected per point.

1. Perspective
   a single style from one perspective
2. Syntax
   allowed, encouraged, prohibited, required
3. Vocabulary
   allowed, encouraged, prohibited, required
4. Formatting
   markdown (indent tab space etc.)
   document (which sections to include in what order)
   each with allowed, encouraged, prohibited, required
5. Figures
   charts, diagrams, images, embedded content
   each with allowed, encouraged, prohibited, required
6. Links
   internal, external
   each with allowed, encouraged, prohibited, required
7. Citations
   allowed, encouraged, prohibited, required

Start by reviewing the existing documentation and the style-related closure referenced as #358. Define a canonical guide covering perspective, syntax, vocabulary, formatting, figures, links, and citations; the issue does not name specific files or tests, so completion criteria would need community agreement.