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.
- Document template testing repos
- Introduce dom0 testing repos
- Cross-link dom0 and domU testing repo sections
- Link to template testing section from related sections
- Add pointer to installing templates
- Minor improvements and fixes
Thanks to @GWeck for pointing out the need for this in:
https://forum.qubes-os.org/t/fedora-34-template-available-for-testing/4904/4
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.
- Convert alert into text warning
(Now that every advanced page has the same sticky alert at the top,
it looks odd to have similar alerts above and below the h1 heading.)
- Update heading syntax
- Wrap text
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
Those are fields used by the language switcher to correlate pages across
different languages, even if they have different names/paths/titles.
They are generated with the prepare_for_translation.py script.
- mark all code blocks with ```
- unify empty lines between sections
- adjust list syntax (no space before dash)
- adjust headers to use Atx-style syntax
- remove trailing spaces
- Consolidate tables to avoid need for cross-referencing
- Drop unsupported versions
- Consolidate and clarify TemplateVM version support policies
- Make formatting and language more consistent
These revisions focus mainly on improving language, presentation, and
organization. The core instructions are largely preserved, though some
new information and links to other resources are added.
Now that we have a user forum in addition to qubes-users, it makes more
sense to link to /support/ than to link directly to qubes-users (or to
the forum, for that matter). This layer of redirection means allows us
to update just one thing (namely, the /support/ page) instead of having
to hunt through all the documentation every time support information
changes.
I have added most of Marek's suggestions. I don't know how to solve the markdown HTML and formatting issue. (I believe alert boxes are great and should be used to make it more visually appealing but alas, it may be a bit too late to settle on this)
