Reorganize doc guidelines into multiple pages; update style guide

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.
This commit is contained in:
Andrew David Wong 2021-07-08 07:41:19 -07:00
parent c4f59952f5
commit c29cf40910
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
15 changed files with 481 additions and 411 deletions

View file

@ -0,0 +1,78 @@
---
lang: en
layout: doc
permalink: /doc/website-style-guide/
title: Website Style Guide
---
This page explains the standards we follow for building and maintaining the
website. Please follow these guidelines and conventions when modifying the
website. For the standards governing the documentation in particular, please
see the [documentation style guide](/doc/documentation-style-guide/).
## Coding conventions
The following conventions apply to the website as a whole, including everything
written in HTML, CSS, YAML, and Liquid. These conventions are intended to keep
the codebase consistent when multiple collaborators are working on it. They
should be understood as a practical set of rules for maintaining order in this
specific codebase rather than as a statement of what is objectively right or
good.
### General practices
- Use comments to indicate the purposes of different blocks of code. This makes
the file easier to understand and navigate.
- Use descriptive variable names. Never use one or two letter variable names.
Avoid obscure abbreviations and made-up words.
- In general, make it easy for others to read your code. Your future self will
thank you, and so will your collaborators!
- [Don't Repeat Yourself
(DRY)!](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) Instead of
repeating the same block of code multiple times, abstract it out into a
separate file and `include` that file where you need it.
### Whitespace
- Always use spaces. Never use tabs.
- Each indentation step should be exactly two (2) spaces.
- Whenever you add an opening tag, indent the following line. (Exception: If
you open and close the tag on the same line, do not indent the following
line.)
- Indent Liquid the same way as HTML.
- In general, the starting columns of every adjacent pair of lines should be no
more than two spaces apart (example below).
- No blank or empty lines. (Hint: When you feel you need one, add a comment on
that line instead.)
#### Indentation example
Here's an example that follows the indentation rules:
{% raw %}
```html
<table>
<tr>
<th title="Anchor Link"><span class="fa fa-link"></span></th>
{% for item in secs.htmlsections[0].columns %}
<th>{{ item.title }}</th>
{% endfor %}
</tr>
{% for canary in site.data.sec-canary reversed %}
<tr id="{{ canary.canary }}">
<td><a href="#{{ canary.canary }}" class="fa fa-link black-icon" title="Anchor link to Qubes Canary row: Qubes Canary #{{ canary.canary }}"></a></td>
<td>{{ canary.date }}</td>
<td><a href="https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-{{ canary.canary }}-{{ canary.date | date: '%Y' }}.txt">Qubes Canary #{{ canary.canary }}</a></td>
</tr>
{% endfor %}
</table>
```
{% endraw %}