The existing doc guidelines page attempts to combine too many different
topics at once and includes information that does not pertain directly
to the documentation. This reorganization is intended to make each type
of information easier to find. For example, some have found it difficult
to find the documentation style guidelines (see, e.g.,
QubesOS/qubes-issues#6701#issuecomment-875875610). This reorganization
allows us to assign more specific titles to each page.
General changes:
- Create new page for contribution instructions
- Create new page for website style guide
- Create new page for continuous integration
- Rename existing "style guide" to "visual style guide" in order to
avoid ambiguity with new doc and website style guides
- Retain existing page solely for doc style guide
- Update page names and permalinks
- Update existing links
- Improve language
Doc style guide changes:
- Add section on using sentence case in headings
(see QubesOS/qubes-issues#6756 and #1173)
- Improve section organization
- Clarify language
In order to better preserve the Git history of each file, file renames
will be handled in a separate commit.
Although the HTMl tags are technically correct, it's probably more
important to preserve source readability and avoid the problems that
HTML-in-Markdown poses for localization and offline documentation.
Those are redundant, and yaml parser strips them in fact. By removing
them, loading and saving yaml file without any change indeed produce the
same output. This is useful for prepare_for_translation.py script (which
adds lang and ref tags) - to produce only change that indeed was made.
- Revamp intro to make it (hopefully) more user-friendly
- Generalize last section into "Unofficial venues"
- Warn that we do not monitor or moderate unofficial venues
- Warn more explicitly about possible Qubes team impostors
- Miscellaneous updates and improvements
- Improve section organization
- Improve new issue instructions
- Add section on "projects"
- Convert final section into "How issues get closed"
- Add section on backports (closesQubesOS/qubes-issues#6655)
