1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
= Documentation Style Guide
:description: Channels, announcements and so on.
:page-nav_order: 3
:page-parent: Contributing
// SPDX-FileCopyrightText: 2023 Unikie
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
Here you can find the standards we follow for writing,
formatting, and organizing the Spectrum documentation.
Please follow these guidelines and conventions
when editing the documentation.
We use https://nixos.org/manual/nix/stable/introduction.html[Nix] and
https://github.com/just-the-docs/just-the-docs[Just the Docs] for
building the documentation. Sources are written in AsciiDoc If you are
new with it, see
https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation].
If you want to test your changes,
see xref:../contributing/building-documentation.adoc[Building Documentation].
== Philosophy
* 1 change = 1 patch
* Update the documentation with the code.
* Organize the AsciiDoc files into subdirectories.
* Keep separate documentation for every different process
to avoid confusion.
* Do not assume that readers know everything you currently know.
* Avoid jargon and acronyms, if you can.
* Avoid multiple variations or spellings to refer to the same
function, element, and so on.
* Write short and useful documents. Cut out everything unnecessary,
while also making a habit of continually improving every doc
to suit your changing needs.
== Document Layout
* https://docs.asciidoctor.org/asciidoc/latest/document/header/[Document header]:
include your name and a revision line following the author line. Example:
= Document Title
:description: Some words about the content.
Author Name <author@example.org>
v1.0, 2012-02-10
//empty line that ends the document header
* Licensing: include license information after a document header. For example:
// SPDX-FileCopyrightText: year / Name, surname / email address or the company name
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
* Double space: the double space after the period is deliberate.
Some people find it improves readability, and others do not like it,
but the reason we use it in Spectrum documentation is that it allows
text editors (Emacs) to differentiate between the ends of sentences
and abbreviations (like "etc."), which means that you can make commands
like "move to the next sentence" work accurately even if those
abbreviations are used.
* Character line limit:
** Keep text hard-wrapped at 70-80 characters. (Most editors should be able
to do this automatically.) This makes it easier to pick out specific parts
in review, and also makes it easier to read in some editors. (It does not make a difference to the result as rendered in the web browser.)
** Keep the text in the description attribute hard-wrapped as well. For more information, see the https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description[Document Metadata] section of the Asciidoctor Docs.
* Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc Recommended Practices].
== Structure
* Use subheading to organize information.
* One topic per article.
* To make accents, use https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonitions].
* Use numbered lists for actions that happen in sequence.
* Do not use parenthesis for additional information, make a separate sentence instead.
== Language
=== Plain English
Plain language is a universal language that makes information clear and better to understand.
* Short, sharp sentences.
* Use simple tenses.
* Write in an active voice.
* Understandable language, fewer gerunds.
* Do not contract the words: use cannot instead of can’t.
* Write the full name when first mentioned with the acronym in brackets.
* Use numerals for numbers.
* Do not use Latin words. For example:
** perform operations, *etc.* => perform operations, *and so on*
** *e.g.* a Microsoft SQL Server => *for example,* a Microsoft SQL Server
** *via* the system => *through* the system
=== Spelling
* Use standard United States (U.S.) English. In cases where US spelling differs
from UK spelling, use the US spelling. There is no need to fix one by
replacing it with the other.
* When you use filenames, URLs, and data parameters in examples, try to avoid words that are spelled differently by different groups of English speakers.
* Use serial (Oxford) commas.
|