You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _doc/developer/general/documentation-style-guide.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,7 +46,7 @@ This rule is important because using absolute URLs for internal website links br
46
46
47
47
### Image linking
48
48
49
-
See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.
49
+
See [how to add images](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.
50
50
51
51
In addition, make sure to link only to images in the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do not attempt to link to images hosted on other websites.
52
52
@@ -242,7 +242,7 @@ We have observed that many novices make the mistake of typing the surrounding an
242
242
243
243
### Capitalization of "qube"
244
244
245
-
We introduced the term ["qube"](/doc/glossary/#qube) as a user-friendly alternative to the term ["virtual machine" ("VM")](/doc/glossary/#vm) in the context of Qubes OS. Nonetheless, "qube" is a common noun like the words "compartment" and "container." Therefore, in English, "qube" follows the standard capitalization rules for common nouns. For example, "I have three qubes" is correct, while "I have three Qubes" is incorrect. Like other common nouns, "qube" should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of "qube" (e.g., "Qubes can be shut down...") can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, [Qubes OS](/doc/glossary/#qubes-os), or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
245
+
We introduced the term ["qube"](https://doc.qubes-os.org/en/latest/user/reference/glossary.html#qube) as a user-friendly alternative to the term ["virtual machine" ("VM")](https://qubes-doc-rst.readthedocs.io/en/latest/user/reference/glossary.html#vm) in the context of Qubes OS. Nonetheless, "qube" is a common noun like the words "compartment" and "container." Therefore, in English, "qube" follows the standard capitalization rules for common nouns. For example, "I have three qubes" is correct, while "I have three Qubes" is incorrect. Like other common nouns, "qube" should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of "qube" (e.g., "Qubes can be shut down...") can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, [Qubes OS](https://qubes-doc-rst.readthedocs.io/en/latest/user/reference/glossary.html#qubes-os), or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
246
246
247
247
Many people feel a strong temptation to capitalize the word "qube" all the time, like a proper noun, perhaps because it's a new and unfamiliar term that's closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it's not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, "blockchain" is a relatively recent technical term that's a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn't change the way we capitalize sentences like, "John sat under a tree." Intuitively, it makes sense that the addition and removal of objects from the world shouldn't cause published books to become orthographicallly incorrect while sitting on their shelves.
248
248
@@ -262,11 +262,11 @@ Duplicating documentation is almost always a bad idea. There are many reasons fo
262
262
263
263
### Core vs. external documentation
264
264
265
-
Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Forum](https://forum.qubes-os.org/docs). External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Forum](https://forum.qubes-os.org/docs) instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Forum](https://forum.qubes-os.org/) should regularly submit PRs against the documentation index (see [How to edit the documentation index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) to add and update Qubes Forum links in the ["External documentation"](/doc/#external-documentation) section of the documentation table of contents.
265
+
Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Forum](https://forum.qubes-os.org/docs). External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Forum](https://forum.qubes-os.org/docs) instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Forum](https://forum.qubes-os.org/) should regularly submit PRs against the documentation index (see [How to edit the documentation index](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#how-to-edit-the-documentation-index)) to add and update Qubes Forum links in the ["External documentation"](https://qubes-doc-rst.readthedocs.io/en/latest/index.html#external-documentation) section of the documentation table of contents.
266
266
267
267
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 particularly 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.
268
268
269
-
Many contributors do not realize that 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 [undergo a review process](/doc/how-to-edit-the-documentation/#security) to ensure accuracy before being merged, 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.
269
+
Many contributors do not realize that 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 [undergo a review process](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#security) to ensure accuracy before being merged, 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.
270
270
271
271
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.
272
272
@@ -352,4 +352,4 @@ For further discussion about release-specific documentation in Qubes, see [here]
Copy file name to clipboardExpand all lines: pages/donate.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -148,20 +148,20 @@ However, if you or your organization has relevant knowledge, experience, leads,
148
148
### How do I verify your Bitcoin address?
149
149
150
150
The donation address can be verified via the [Qubes Security Pack](/security/pack/), specifically in the [fund directory](https://github.com/QubesOS/qubes-secpack/tree/master/fund).
151
-
We provide [detailed instructions for verifying the digital signatures](/security/pack/#how-to-obtain-and-authenticate).
151
+
We provide [detailed instructions for verifying the digital signatures](https://doc.qubes-os.org/en/latest/project-security/security-pack.html#how-to-obtain-and-authenticate).
152
152
153
153
The Qubes Project maintains a [decentralized Bitcoin fund using a multi-signature wallet](/news/2016/07/13/qubes-distributed-fund/).
154
154
This means that no single person is capable of spending these funds.
155
155
156
156
### How do I verify your Ethereum address?
157
157
158
158
The donation address can be verified via the [Qubes Security Pack](/security/pack/), specifically in the [fund directory](https://github.com/QubesOS/qubes-secpack/tree/master/fund).
159
-
We provide [detailed instructions for verifying the digital signatures](/security/pack/#how-to-obtain-and-authenticate).
159
+
We provide [detailed instructions for verifying the digital signatures](https://doc.qubes-os.org/en/latest/project-security/security-pack.html#how-to-obtain-and-authenticate).
160
160
161
161
### How do I verify your Monero address?
162
162
163
163
The donation address can be verified via the [Qubes Security Pack](/security/pack/), specifically in the [fund directory](https://github.com/QubesOS/qubes-secpack/tree/master/fund).
164
-
We provide [detailed instructions for verifying the digital signatures](/security/pack/#how-to-obtain-and-authenticate).
164
+
We provide [detailed instructions for verifying the digital signatures](https://doc.qubes-os.org/en/latest/project-security/security-pack.html#how-to-obtain-and-authenticate).
<p>Have questions or need a hand? As a free and open-source project, our valued community of users and contributors from around the world are in the best position to help. Before diving in, we encourage you to read about <ahref="/support/#staying-safe">staying safe</a>, our <ahref="/support/#discussion-guidelines">discussion guidelines</a>, and our <ahref="/code-of-conduct/">code of conduct</a> to help keep things positive and on-track. We welcome newcomers and returning users wanting to discuss Qubes and <ahref="/doc/contributing/">seeking to contribute</a>.
238
+
<p>Have questions or need a hand? As a free and open-source project, our valued community of users and contributors from around the world are in the best position to help. Before diving in, we encourage you to read about <ahref="https://doc.qubes-os.org/en/latest/introduction/support.html#staying-safe">staying safe</a>, our <ahref="https://qubes-doc-rst.readthedocs.io/en/latest/introduction/support.html#discussion-guidelines">discussion guidelines</a>, and our <ahref="/code-of-conduct/">code of conduct</a> to help keep things positive and on-track. We welcome newcomers and returning users wanting to discuss Qubes and <ahref="/doc/contributing/">seeking to contribute</a>.
0 commit comments