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.
- Update contribution steps and first two images
- Improve source formatting and consistency
- Add information
- Improve organization and add subheadings
- Clarify and improve wording
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.
There appears to be no strong reason that these pages are using a
different layout, and having this separate layout significantly
increases the ongoing doc maintenance burden.
- Convert "Common Tasks" to "How-to Guides"
(QubesOS/qubes-issues#6694)
- Make title capitalization consistent across docs
- Fix leftover h1 headings
- Reorganize various pages and topics
- Update permalinks to better match titles
- Create redirects for changed permalinks
- Miscellaneous cleanup
QubesOS/qubes-issues#6701
- Create separate section for editing doc index
- Link to how-to-edit-doc-index section in contrib guide
- Link to how-to-edit-doc-index section in core vs. external section
- Link to how-to-add-images section in contrib guide
- Add "PR" abbreviation for those unfamiliar (not used on this
page but often used elsewhere and when linking to this page)
See QubesOS/qubes-issues#6694
