Add guidelines on duplication and core vs. external docs

- Add new "Organizationl guidelines" section
 - Add some relevant links in other sections
 - Update heading syntax to account for new h3s
 - Normalize heading case

developer/general/doc-guidelines.md

@@ -8,8 +8,7 @@ redirect_from:
 - /doc/DocStyle/
 ---
 
-Documentation Guidelines
-========================
+# Documentation guidelines
 
 All Qubes OS documentation pages are stored as plain text files in the dedicated [qubes-doc] repository.
 By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
@@ -18,8 +17,9 @@ The documentation is a community effort. Volunteers work hard trying to keep eve
 If you notice a problem or some way it can be improved, please [edit the documentation][contribute]!
 
 
-Security
---------
+## Security
+
+*Also see: [Should I trust this website?]()*
 
 All pull requests against [qubes-doc] must pass review prior to be merged, except in the case of [external documentation] (see [#4693]).
 This process is designed to ensure that contributed text is accurate and non-malicious.
@@ -34,8 +34,7 @@ If so, the documentation maintainer then merges the pull request, adds a PGP-sig
 In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
 
 
-Questions, problems, and improvements
--------------------------------------
+## Questions, problems, and improvements
 
 If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
 If you see that something in the documentation should be fixed or improved, please [contribute] the change yourself.
@@ -43,8 +42,7 @@ To report an issue with the documentation, please follow our standard [issue rep
 (If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
 
 
-How to Contribute
------------------
+## How to contribute
 
 Editing the documentation is easy, so if you see that a change should be made, please contribute it!
 
@@ -116,8 +114,7 @@ If, for some reason, we can't accept your pull request, we'll post a comment exp
 ![done](/attachment/wiki/doc-edit/10-done.png)
 
 
-How to add images
------------------
+### How to add images
 
 To add an image to a page, use the following syntax in the main document:
 
@@ -130,8 +127,55 @@ This is the only permitted way to include images.
 Do not link to images on other websites.
 
 
-Version-specific Documentation
-------------------------------
+## Organizational guidelines
+
+### Do not duplicate documentation
+
+Duplicating documentation is almost always a bad idea.
+There are many reasons for this.
+The main one is that almost all documentation has to be updated as some point.
+When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn't realize it's in more than once place).
+When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users.
+Such traps are often more harmful than if the documentation never existed in the first place.
+The solution is to **link** to existing documentation rather than duplicating it.
+There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare.
+
+### Core vs. external documentation
+
+*See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more information.*
+
+Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc].
+External documentation can be anywhere else (such as fan websites and personal blogs), but there is an especially large collection in the [Qubes Community](https://github.com/Qubes-Community) project.
+External documentation should not be submitted to [qubes-doc].
+If you've written a piece of documentation that is not appropriate for [qubes-doc], we encourage you to submit it to the [Qubes Community](https://github.com/Qubes-Community) project instead.
+At the time of this writing, there is also a section of external documentation in [qubes-doc] that is in the process of being moved to the [Qubes Community](https://github.com/Qubes-Community) project (see [#4693](https://github.com/QubesOS/qubes-issues/issues/4693)).
+
+The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project.
+The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project.
+In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else.
+For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/).
+However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own.
+This is particular true when it comes to Linux in general.
+Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.
+
+Many contributors do not realize that the there is a significant amount of work involved in *maintaining* documentation after it has been written.
+They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward.
+Submissions to the core docs also have to go through a review process to ensure accuracy before being merged (see [security](#security)), which takes up valuable time from the team.
+We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time.
+If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes.
+It's also important to periodically review and update this documentation, especially when a new Qubes release comes out.
+Periodically, there may be technical or policy changes that affect all the core documentation.
+The more documentation there is relative to maintainers, the harder all of this will be.
+Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.
+
+On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world.
+The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes.
+In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as `qrexec`, it does not make sense to include every tutorial that says "here's how to do something cool with `qrexec`" in the core docs.
+Such tutorials generally also belong in the community documentation.
+
+### Version-specific documentation
+
+*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential changes to this policy.*
 
 We maintain only one set of documentation for Qubes OS.
 We do not maintain a different set of documentation for each version of Qubes.
@@ -141,7 +185,7 @@ Our second priority is to document the next, upcoming release (if any) that is c
 
 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 ###
+#### Incorrect Example
 
 ```
 # Page Title #
@@ -166,7 +210,7 @@ command introduced in 4.0:
 Once you foo, make sure to close the baz before fooing the next bar.
 ```
 
-### Correct Example ###
+#### Correct Example
 
 ```
 # Page Title #
@@ -236,8 +280,7 @@ Good general content that was submitted only to one branch would effectively dis
 For further discussion about version-specific documentation in Qubes, see [here][version-thread].
 
 
-Style Guidelines
-----------------
+## Style guidelines
 
  * Familiarize yourself with the terms defined in the [glossary]. Use these
    terms consistently and accurately throughout your writing.
@@ -256,8 +299,7 @@ Style Guidelines
    3. Using all capital letters
 
 
-Markdown Conventions
---------------------
+## Markdown conventions
 
 All the documentation is written in Markdown for maximum accessibility.
 When making contributions, please try to observe the following style conventions:
@@ -313,8 +355,7 @@ When making contributions, please try to observe the following style conventions
 ([This][md] is a great source for learning about Markdown.)
 
 
-Git Conventions
----------------
+## Git conventions
 
 Please try to write good commit messages, according to the
 [instructions in our coding style guidelines][git-commit].