patches and low-level development discussion
 help / color / mirror / code / Atom feed
9c1d5fb069684d70c9cfa51fb8b1c9bc67a60135 blob 4621 bytes (raw)

  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: 2
: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 xref:https://nixos.org/manual/nix/stable/introduction.html[Nix]
and xref: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 xref: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

* xref: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 xref: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 xref: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 xref: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.
debug log:

solving 9c1d5fb ...
found 9c1d5fb in https://spectrum-os.org/lists/archives/spectrum-devel/20230119154307.28303-1-evgeniia.nikolaenko@unikie.com/

applying [1/1] https://spectrum-os.org/lists/archives/spectrum-devel/20230119154307.28303-1-evgeniia.nikolaenko@unikie.com/
diff --git a/Documentation/contributing/writing_documentation.adoc b/Documentation/contributing/writing_documentation.adoc
new file mode 100644
index 0000000..9c1d5fb

1:18: trailing whitespace.
when editing the documentation. 
1:101: trailing whitespace.
** *e.g.* a Microsoft SQL Server => *for example,* a Microsoft SQL Server 
Checking patch Documentation/contributing/writing_documentation.adoc...
Applied patch Documentation/contributing/writing_documentation.adoc cleanly.
warning: 2 lines add whitespace errors.

index at:
100644 9c1d5fb069684d70c9cfa51fb8b1c9bc67a60135	Documentation/contributing/writing_documentation.adoc

Code repositories for project(s) associated with this public inbox

	https://spectrum-os.org/git/crosvm
	https://spectrum-os.org/git/doc
	https://spectrum-os.org/git/mktuntap
	https://spectrum-os.org/git/nixpkgs
	https://spectrum-os.org/git/spectrum
	https://spectrum-os.org/git/ucspi-vsock
	https://spectrum-os.org/git/www

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).