From dc86a9af85647f1ba79cff24b8d53c5fe561c571 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 31 Mar 2018 09:53:59 -0500 Subject: [PATCH] Explain version-specific practices and provide examples This is intended to address the sort of query asked in https://github.com/QubesOS/qubes-doc/pull/622 --- basics_user/doc-guidelines.md | 90 ++++++++++++++++++++++++++++++++++- 1 file changed, 89 insertions(+), 1 deletion(-) diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index e58459e8..2a597593 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -125,7 +125,93 @@ We do not maintain a different set of documentation for each version of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all **current, stable releases** of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. -In cases where a documentation page covers functionality that differs considerably between Qubes OS versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions. + +In cases where a documentation page covers functionality that differs considerably between Qubes OS versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions: + +### Incorrect Example ### + +``` +# Page Title # + +## How to Foo ## + +Fooing is the process by which one foos. There are both general and specific +versions of fooing, which vary in usefulness depending on your goals, but for +the most part, all fooing is fooing. + +To foo in Qubes 3.2: + + $ qvm-foo + +Note that this does not work in Qubes 4.0, where there is a special widget +for fooing, which you can find in the lower-right corner of the screen in +the Foo Manager. Alternatively, you can use the more general `qubes-baz` +command introduced in 4.0: + + $ qubes-baz --foo + +Once you foo, make sure to close the baz before fooing the next bar. +``` + +### Correct Example ### + +``` +# Page Title # + +## Qubes 3.2 ## + +### How to Foo ### + +Fooing is the process by which one foos. There are both general and specific +versions of fooing, which vary in usefulness depending on your goals, but for +the most part, all fooing is fooing. + +To foo: + + $ qvm-foo + +Once you foo, make sure to close the baz before fooing the next bar. + + +## Qubes 4.0 ## + +### How to Foo ### + +Fooing is the process by which one foos. There are both general and specific +versions of fooing, which vary in usefulness depending on your goals, but for +the most part, all fooing is fooing. + +There is a special widget for fooing, which you can find in the lower-right +corner of the screen in the Foo Manager. Alternatively, you can use the +general `qubes-baz` command: + + $ qubes-baz --foo + +Once you foo, make sure to close the baz before fooing the next bar. +``` + +[Here][version-example] is a good example of a page that is correctly subdivided to account for version-specific differences. +Clearly subdividing the page into clearly-labeled sections for each version has several benefits: + + * It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version. + * It's hard for readers to miss information they need, since it's all in one place. + In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page. + In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. + The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice. + Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated. + Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing: + We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software. + * It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions. + Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions. + +By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. +Most of the time, this wouldn't happen. +When it did, it would mean a second pull request that would have to be reviewed. +Over time, the different branches would diverge in non-version-specific content. +Good general content that was submitted only to one branch would effectively disappear once that version was deprecated. +(Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated version, and there would be a motivation to remove it from the website so that search results wouldn't be populated with out-of-date information.) + +For further discussion about version-specific documentation in Qubes, see [here][version-thread]. Contribution Suggestions @@ -200,6 +286,8 @@ Please try to write good commit messages, according to the [gh-pull]: https://help.github.com/articles/using-pull-requests/ [GitHub]: https://github.com/ [mailing lists]: /mailing-lists/ +[version-example]: /doc/template/fedora/upgrade-25-to-26/ +[version-thread]: https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion [QSBs]: /security/bulletins/ [News]: /news/ [md]: https://daringfireball.net/projects/markdown/