Documentation Style and Formatting
English style
Write short sentences. Organize concepts in paragraphs. Prefer lists to tables and paragraphs to lists. Write in the active voice. Avoid jargon beyond the requirements of subject and audience.
Eschew you
You write unambiguous documentation, so you avoid the second person. Avoiding personal pronouns in general helps produce the imperative impersonal tone desired for documentation. Don’t reboot your system or have the user reboot their system. Reboot the system.
Generalities
There are a few other common ways to write or not write things:
- Expand acronyms on their introduction in a document, with the short form following in parentheses: Trusted Platform Module (TPM).
- Terms of art that are not commands or other literal text should often be italicized on their first appearance in a document: Kubernetes is a good example.
- The hyphen is overused and most English compounds do not require it .
- There is one space (
.
), comma (,
), semicolon (;
) and other marks of punctuation.
Specifics
There are a few prescribed ways of writing frequently questioned words and phrases:
- The singular possessive form of CoreOS is CoreOS’s. CoreOS’s mission is to secure the infrastructure that powers the Internet.
- Deployments may occur on-premises, sometimes “on-prem,” but never on-premise. A premises is a place. A premise is a proposition.
- GIFEE was formerly Google’s Infrastructure for Everyone Else, but now it is Google’s Infrastructure for EveryonE.
Project names are proper nouns
Project names are proper nouns written with an initial capital letter. Examples include Ignition, Dex, and Matchbox.
The Linux distribution is called Flatcar Container Linux.
These capitalization rules are traditional and arcane. They should eventually give way to all project and product names being capitalized as proper nouns, except when given literally, e.g., rkt run docker://nginx
or /var/lib/rkt
.
Unix style: Command line grammar
Commands invoke or execute programs. Commands take arguments and accept options, which themselves may be set to values.
Example: Documenting echo(1)
In this simple command line:
$ echo -n Example
Example
echo
is the command, and Example
is the argument. The option -n
suppresses the terminating newline usually emitted by echo
. A binary option represented by a single letter, like -n
, is sometimes called a flag. The echo(1)
command prints its argument on the standard output, and a good shell excerpt often includes the expected output of commands, as shown here. The shell prompt character $
distinguishes input from output.
Example: Documenting subcommands
Some command lines are more complex. Many commands operate through a set of subcommands. rkt
and several other relevant programs follow this pattern.
$ rkt run --debug example.aci
[...]
In this case the argument to rkt
, run
, is a subcommand. run
in turn accepts the --debug
option to modify how it executes the ACI image specified by its own argument, example.aci
Example: Documenting long command lines
Some commands pack many subcommands, arguments, and options on a single line. It is good practice to break such long command lines with newlines, escaped with backslash (\
), because lines inside code blocks are not soft-wrapped in most presentations. For very long command lines, choose points that break the parameters into logical groups. Lines so wrapped are not indented for vertical alignment.
$ docker run --name docsbuilder \
-i -t \
-p 80:9001 -p 443:9443 \
-v /home/core/site:/app:rw \
-v /etc/ssl/certs:/etc/ssl/certs:ro \
quay.io/coreosinc/coreos-pages-builder scripts/deploy stage
Comment conventions
Add comments inline if possible, and before the referenced line of code if not.
staticPasswords:
- email: "[email protected]"
# bcrypt hash of the string "password".
hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
username: "admin" # username to display. NOT used during login.
userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"
Placeholder conventions
Use these standard example entities to avoid exposing real URLs, IP Addresses, or other data.
- URL: example.com
- IP Address: Any in the range 203.0.113.0/24
Source formatting
Flatcar documentation is written in Markdown , a simple way to annotate text to indicate presentation typesetting. Markdown source is intended to be a plain text human-readable version of the document, even before conversion to HTML for the browser or other display.
Source file naming and encoding
Write Markdown source in UTF-encoded plain text files, named with a reasonable, lower case short form of the document’s title, and suffixed with ``. Prefer hyphens to underscores in file names with two or more words. For example, instructions for DNS configuration are written to a file named
configuring-dns
.
Line wrapping considered harmful
Don’t wrap long lines of text with manual newlines. Line wrapping churns prose documents, because lines not actually edited will nevertheless change when a paragraph is edited and rewrapped.
One sentence per line deprecated
Do not add a line break between sentences. Write natural English paragraphs, separated by a single blank line. Writing Markdown source with a newline between every sentence is acceptable to most compilers and can ease change review. However, this format makes the document less readable in source form.
Preferred markdown symbols
Markdown defines two or more ways to declare some document structures. This documentation prefers these Markdown symbols among their alternatives:
- Headings are denoted in Markdown’s ATX style, with hash character(s):
#
. See Headings , below. - Bulleted lists, like this one, are denoted with the asterisk (
*
), rather than the hyphen. - Hyperlink URLs are given in the reference style (
[hyperlinked text][label]
), rather than inline. Hyperlink labels are defined in one list at the end of the document. Relative links are preferred to absolute links. See Hyperlink Considerations , below. - Italic text is wrapped with a pair of single asterisks:
*Italics*
; Bold with a double pair:**Bold**
. Monospace
is indicated between a pair of backticks. This distinguishes literal strings like command names, file paths, or values, e.g.,/bin/markdown
. See Command Line Grammar , below.- Longer code blocks or file contents are fenced: Set off on new lines between pairs of three backticks, rather than indented. A presentation hint specifying the block’s language can be given immediately after the opening three backticks, e.g., ````yaml`.
Headings
By convention, the level one heading, denoted in Markdown by a single hash character (#
), is the document’s title. This document’s title is Documentation style and formatting.
Heading style
Each heading is both preceded and followed by a newline. A space separates the Markdown symbols from the heading text. Headings are typed in Sentence case, capitalizing the first letter of the first word, but other words only as they would be capitalized if appearing in the middle of a sentence.
Heading semantics and the sidebar outline
Section headings expose the document’s logical structure with a notation of incrementing hash marks (#[#][...]
) for increasingly nested levels of a hierarchy. With the level one heading devoted to the document title, the second-level headings represent the document’s primary concepts.
The site deployment process inspects a document’s headings to derive the thumb index outlines seen in the right sidebar of documentation viewed at docs.flatcar-linux.org .
Example: This document’s source
The abridged skeletal markdown source for this document’s headings:
# Documentation style and formatting
## English style
### Eschew you
[...]
## Headings
### Heading style
[...]
## Unix style: Command line grammar
### Example: Documenting `echo(1)`
[...]
## Hyperlink considerations
### Naming
### Marking down the link
#### Example: Reference-style hyperlinking
[...]
## File name extension conventions
Example: The “average” document
Most documents have a single h1
(#
) heading matching the title, two to five h2
(##
) headings representing the topic’s primary concepts, and one or two h3
(###
) and h4
(####
) headings organizing details beneath each h2
.
If a document proves a great deal longer or more structurally complex than those simplistic rules of thumb, there should be a good reason.
Hyperlink considerations
Naming
Name hyperlinks carefully to give them maximum context. For example, note that certain information is in the style guide , rather than just pointing lazily to the style guide here . The link text “here” gives almost no information about its target. It is helpful to write a clear sentence first, then bracket the choice words within to declare them a hyperlink.
Marking down the link
As mentioned above, the reference style of Markdown hyperlinking is preferred to the inline. Hyperlinks are marked with two pairs of square brackets, the first enclosing the hyperlinked text, the second enclosing a label for the link. Labels are in turn associated with a target URL in a list of declarations at the end of the document. Each label declaration consists of a line beginning with the bracket-enclosed label, a colon, and the target URL (the href
in HTML). The target URL may optionally be followed by a link title in double quotes. The list of link label declarations should be sorted alphabetically.
Example: Reference-style hyperlinking
The reference style of [Markdown hyperlinks][mdlinks] allows for easier
reading of source and formalizes the declaration of links.
Another paragraph may reference the [project introduction][readme],
which link will likewise have its label defined at the document's foot.
[mdlinks]: http://daringfireball.net/projects/markdown/syntax#link "Markdown link syntax"
[readme]: README
Relative URLs preferred
Using relative URLs where possible helps portability among multiple presentation targets, as they remain valid even as the site root moves. Absolute linking is obviously necessary for resources external to the document’s repository and/or the docs.flatcar-linux.org domain.
For example, there are two ways to refer to the
Flatcar quick start guide
’s location. The preferred way is a relative link from the current file’s path to the target, which from this document is ../../installing
. An absolute link to the complete URL is less flexible, and more verbose: https://github.com/flatcar/flatcar-website/blob/master/content/docs/latest/installing/_index.md
.
Hyperlink deployment automation
CoreOS documents have two major publication targets: the
docs.flatcar-linux.org documentation
, and
GitHub’s Markdown presentation
. The deployment scripts used to build the CoreOS site handle some of the wrinkles arising between the two targets. These scripts expect links to other CoreOS project documentation to refer to the Markdown source; that is, to end with the .md
file extension. The deployment scripts rewrite hyperlinks to replace that extension with .html
for presentation. This allows the links to be valid in either context. External links are not rewritten.
Example: Documenting code blocks
Insert triple backtick (grave accent) characters on a new line before and after a block of code. A tag, such as yaml
, sh
, json
, or ini
, can be placed after the opening backticks to declare the language in the block. Markdown syntax is not interpreted within the gated code block, but special characters are replaced with HTML entities.
apiVersion: v1
kind: Service
metadata:
name: etcd-client
spec:
ports:
- name: etcd-client-port
port: 2379
protocol: TCP
targetPort: 2379
selector:
app: etcd
View this document’s source to see the Markdown that generates the code block above.
File name extension conventions
Some file types are commonly identified with more than one file name extension. For example, YAML is usually stored in files whose names end in either .yml
, or .yaml
. For the sake of consistency, use the file name extension designated in the following list when referring to or creating files of any of the listed types in CoreOS projects and their documentation.
- YAML:
file.yaml
is preferred tofile.yml
- HTML:
file.html
, notfile.htm