Skip to content

Commit

Permalink
Update other links to specific sections
Browse files Browse the repository at this point in the history
Redirects break section anchors, so put target links directly there.
  • Loading branch information
marmarek committed Jan 8, 2024
1 parent f0550ed commit 636f24e
Show file tree
Hide file tree
Showing 9 changed files with 17 additions and 17 deletions.
2 changes: 1 addition & 1 deletion _data/downloads-page.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,5 +40,5 @@
- column: Location
- column: URL
links:
- url: /downloads/mirrors/#instructions-for-mirror-operators
- url: https://qubes-doc-rst.readthedocs.io/en/latest/user/downloading-installing-upgrading/download-mirrors.html#instructions-for-mirror-operators
text: How to contribute a download mirror
4 changes: 2 additions & 2 deletions _data/hcl.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
- url: '#hardware-motherboards'
text: Motherboards
id: 3
- url: /doc/how-to-use-the-hcl/#generating-and-submitting-new-reports
- url: https://qubes-doc-rst.readthedocs.io/en/latest/user/hardware/how-to-use-the-hcl.html#generating-and-submitting-new-reports
text: Add your device
id: 4

Expand All @@ -20,7 +20,7 @@
- url: /doc/how-to-use-the-hcl/
text: What is the hardware compatibility list (HCL)?
id: 1
- url: /doc/how-to-use-the-hcl/#generating-and-submitting-new-reports
- url: https://qubes-doc-rst.readthedocs.io/en/latest/user/hardware/how-to-use-the-hcl.html#generating-and-submitting-new-reports
text: How do I submit a report?
id: 2
- url: /doc/system-requirements/
Expand Down
10 changes: 5 additions & 5 deletions _doc/developer/general/documentation-style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ This rule is important because using absolute URLs for internal website links br

### Image linking

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.
See [how to add images](https://qubes-doc-rst.readthedocs.io/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.

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.

Expand Down Expand Up @@ -242,7 +242,7 @@ We have observed that many novices make the mistake of typing the surrounding an

### Capitalization of "qube"

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.
We introduced the term ["qube"](https://qubes-doc-rst.readthedocs.io/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.

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.

Expand All @@ -262,11 +262,11 @@ Duplicating documentation is almost always a bad idea. There are many reasons fo

### Core vs. external documentation

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.
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://qubes-doc-rst.readthedocs.io/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.

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.

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.
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://qubes-doc-rst.readthedocs.io/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.

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.

Expand Down Expand Up @@ -352,4 +352,4 @@ For further discussion about release-specific documentation in Qubes, see [here]

## Git conventions

Please follow our [Git commit message guidelines](/doc/coding-style/#commit-message-guidelines).
Please follow our [Git commit message guidelines](https://qubes-doc-rst.readthedocs.io/en/latest/developer/code/coding-style.html#commit-message-guidelines).
4 changes: 2 additions & 2 deletions _doc/developer/general/how-to-edit-the-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,12 +159,12 @@ especially when your changes affect formatting, images, tables, styling, etc.

## Security

*Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)*
*Also see: [Should I trust this website?](https://qubes-doc-rst.readthedocs.io/en/latest/introduction/faq.html#should-i-trust-this-website)*

All pull requests (PRs) against
[qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be
merged, except in the case of [external
documentation](/doc/#external-documentation) (see
documentation](https://qubes-doc-rst.readthedocs.io/en/latest/index.html#external-documentation) (see
[#4693](https://github.com/QubesOS/qubes-issues/issues/4693)). This process is
designed to ensure that contributed text is accurate and non-malicious. This
process is a best effort that should provide a reasonable degree of assurance,
Expand Down
2 changes: 1 addition & 1 deletion pages/canary.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ title: Qubes canaries
---

A **Qubes canary** is a security announcement periodically issued by the [Qubes
security team](/security/#qubes-security-team) through the [Qubes security
security team](https://qubes-doc-rst.readthedocs.io/en/latest/project-security/security.html#qubes-security-team) through the [Qubes security
pack](/security/pack/) consisting of several statements to the effect that the
signers of the canary have not been compromised. The idea is that, as long as
signed canaries including such statements continue to be published, all is
Expand Down
6 changes: 3 additions & 3 deletions pages/donate.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,20 +148,20 @@ However, if you or your organization has relevant knowledge, experience, leads,
### How do I verify your Bitcoin address?

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).
We provide [detailed instructions for verifying the digital signatures](/security/pack/#how-to-obtain-and-authenticate).
We provide [detailed instructions for verifying the digital signatures](https://qubes-doc-rst.readthedocs.io/en/latest/project-security/security-pack.html#how-to-obtain-and-authenticate).

The Qubes Project maintains a [decentralized Bitcoin fund using a multi-signature wallet](/news/2016/07/13/qubes-distributed-fund/).
This means that no single person is capable of spending these funds.

### How do I verify your Ethereum address?

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).
We provide [detailed instructions for verifying the digital signatures](/security/pack/#how-to-obtain-and-authenticate).
We provide [detailed instructions for verifying the digital signatures](https://qubes-doc-rst.readthedocs.io/en/latest/project-security/security-pack.html#how-to-obtain-and-authenticate).

### How do I verify your Monero address?

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).
We provide [detailed instructions for verifying the digital signatures](/security/pack/#how-to-obtain-and-authenticate).
We provide [detailed instructions for verifying the digital signatures](https://qubes-doc-rst.readthedocs.io/en/latest/project-security/security-pack.html#how-to-obtain-and-authenticate).

### Is Qubes merchandise available?

Expand Down
2 changes: 1 addition & 1 deletion pages/home.html
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,7 @@ <h2 class="text-center outer-heading"><i class="fa fa-users"></i> Join the Commu
</div>
<div class="white-box more-bottom">
<div class="row">
<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 <a href="/support/#staying-safe">staying safe</a>, our <a href="/support/#discussion-guidelines">discussion guidelines</a>, and our <a href="/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 <a href="/doc/contributing/">seeking to contribute</a>.
<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 <a href="https://qubes-doc-rst.readthedocs.io/en/latest/introduction/support.html#staying-safe">staying safe</a>, our <a href="https://qubes-doc-rst.readthedocs.io/en/latest/introduction/support.html#discussion-guidelines">discussion guidelines</a>, and our <a href="/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 <a href="/doc/contributing/">seeking to contribute</a>.
</div>
<div class="clearfix"></div>
<div class="row more-bottom">
Expand Down
Loading

0 comments on commit 636f24e

Please sign in to comment.