Documentation style and format recommendation for the project

The following recommendations apply to text provided as part of project sources (including the README, AUTHORS and LICENSE files mandated in CLASS (C Language Style for Scalability) and in-line comments which may be parsed into text files and further into generated documentation) in order to facilitate a common style of original readable textual content, and to minimize the amount of tools needed to re-process it into different end-user formats.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF RFC 2119 (see "Key words for use in RFCs to Indicate Requirement Levels").

  • Guidelines regarding plaintext markup formats:

    • Documentation provided and maintained as part of the project SHALL NOT use file formats that require non-FOSS software for processing. Plaintext files are preferred for text documentation, PNG for raster graphics and SVG for vector graphics. Project SHOULD consider that the build farm hosts MAY not have installed the graphical environment and desktop/GUI document processing software, so optional generation of documentation in formats comfortable for end-user consumption SHOULD rely on common processing tools outlined in the "Dependencies" section of CLASS.

    • Committed text and documentation files SHOULD use asciidoc markup if they are structured (including sources for "man" pages, project standards and contracts, user or developer instructions, etc.)

    • Texts MAY be in other markups (e.g. plain ASCII, or markdown) only if they were originally imported from other sources or projects, and if regular subsequent synchronisation, re-import or other comparison to origin of these files is anticipated (e.g. a copy of the standard text of a license chosen by the project, or third party project sources co-distributed as a dependency — where such projects encourage co-distribution rather than release/package dependencies with a clean separation of borders), or if the text file is unstructured (e.g. a line-by-line list of authors without categories… note that almost anything else is inherently structured).

    • Project building recipes MAY assume by default that asciidoc program is the proper tool for processing of committed (or interim generated) text files into other end-user formats, such as MAN, HTML or PDF variants of the documentation. Any other cases should be specifically handled by the recipes as exceptions to the common rule.

    • It is RECOMMENDED that source text files using asciidoc-compatible markup be named with an .asciidoc or .adoc extension (consistently for the whole project), rather than the common indeterminate .txt extension or lack of any extension.

    • It is RECOMMENDED that text files in non-asciidoc compatible markups use their appropriate extensions (e.g. .md for MarkDown), rather than a common indeterminate .txt extension or lack of any extension.

  • Guidelines on use of whitespaces and blank lines:

    • Paragraphs, separate lists of items, code example blocks and other similar groupings of content lines processed specially by the rendering tools SHALL be separated (preceded and followed) by at least one blank line. Section headers MAY be visibly stressed by preceding or surrounding them with two blank lines; if picked, this formatting option should be applied consistently to the whole document.

    • Trailing whitespace characters (SPACE, TAB) and lines fully consisting of whitespace SHOULD be avoided.

    • Sequences of more than one whitespace (e.g. two or more SPACE characters in a row) SHOULD be avoided, wherever such sequences are not part of indentation or do not carry other contextual meaning.

    • If a style is picked to separate sentences in a paragaph with a period . followed by two SPACE characters, this style SHALL be used consistenly in the whole document.

  • Depending on contents, one of several formatting styles may be applicable to lists of items:

    • Lines of bulleted or numbered lists SHALL have the same style regarding a final punctuation character, consistent within at least the list itself — usually semicolon ; for relatively short entries, period . for full sentences (especially when there are several sentences per list item), and a comma , optionally with trailing conjunctions (and/or) for shortest entries that can be read together as parts of a larger sentence; and the last line of the list SHALL end with a period . character.

    • An alternative style is to have no trailing punctuation for list items which otherwise are each a single regular sentence. For lists represented with such choice of style, the consistent option is that the last line also has no punctuation (no period .) as its last character.

    • If an explanatory (semi-)sentence or paragraph precedes such a list, that sentence SHOULD end with a colon : followed by a blank line (for asciidoc markup). If the preceding sentence or paragraph is not an introduction into the contents of the list, it SHOULD be formatted as a usual paragraph, ending with a period . character.

    • Nested lists are considered as separate lists; the last line of each such list at the same level of indentation SHALL end with a period . character (if any punctuation is used to terminate preceding lines of this list).

  • Standard ASCII characters SHALL be preferred over equivalents from the extended Unicode range, such as:

    • three period characters ... over an an ellipsis character "…", or

    • the numerous ways to type a single or double quote, or

    • the use of plain "minus" - or double-minus -- characters over different long-dash characters, and

    • use of asciidoc (or equivalent) plaintext markup like (TM) or (C) instead of singular characters like ™ or ©.

  • Guidelines regarding example code blocks with command-line interfaces:

    • It is RECOMMENDED to precede documentation examples of command-line usage of Unix shell constructs with the colon+semicolon :; as the placeholder of interactive shell prompt at start of a line followed by a single space character (this allows for easy copying and pasting of multi-line examples from documentation into command line, since the sequence would be interpreted by most shells as a non-fatal and non-consequential operation, running or short-circuiting the true command in place of the colon : character).

    • For similar reasons it is RECOMMENDED to parametrize the probable variables in the example shell code snippets (such as URLs or filenames), especially if they are repeated more than once.

    • Likewise, it is RECOMMENDED to organize logical chains (where the subsequent command should only be executed if a previous one did not fail) using the && shell sequence.

    • If the example command-line is longer than 70 characters, it SHOULD be split into multiple lines "concatenated" by trailing backslash as is common in shell scripts; continuation lines SHOULD be indented by at least the length of the shell prompt placeholder (3 spaces for the :; recommended prompt and separator that follows).

    • If the command-line example block includes output from the command to be entered by the reader, the example command SHOULD be separated by a blank line from the sample (or expected) output.

    • If multiple related but separate example code lines follow each other in the same example code block, they MAY be presented without blank lines in between. However, if there is also sample output, the rule above applies, and if the example commands continue after the sample output, it is additionally RECOMMENDED to separate the output from next commands by two blank lines.

    • If an explanatory (semi-)sentence or paragraph precedes example code, that sentence SHOULD end with a colon : followed by a blank line (for asciidoc markup). If the preceding sentence or paragraph is not an introduction into the contents of the example, it SHOULD be formatted as a usual paragraph, ending with a period . character.

    • If the sentence after a source-code example effectively continues the sentence interjected by the block with source-code example, that continuation line SHOULD start with triple-dots and a lower-case character in the first word. For clarity, it is RECOMMENDED to phrase the text in such a manner that singular sentences are not "interrupted" by large blocks of example code.

  • Other typographical conventions as applicable to plaintext documents:

    • Line lengths SHOULD NOT exceed 78 characters, and SHOULD NOT vary greatly in the middle of a paragraph (the RECOMMENDED line length ranges from 66 to 76 characters).

    • Long paragraphs broken into several lines SHALL use whole-word wrapping.

    • In-line short ranges of "verbatim" text, such as filenames and keywords, SHALL be enclosed in backticks `` (for asciidoc markup, or its equivalent for other formats). Verbatim text SHALL NOT be decorated otherwise (italic, bold, underline) if the surrounding text in the paragraph is not decorated so.

    • Introduction or other stressing of terminology SHOULD be enclosed in double quotes.

    • Sentences separated by a tiree (long-dash) SHALL use a sequence of two "minus" characters -- surrounded by single SPACE characters; if such separation happens at end of a line, then the two minuses preceded by a SPACE character SHALL be the last characters in the line (no trailing SPACE, and no lines starting with a carried-over double-minus).

    • Words joined by a dash, mathematical negative numbers and substrations SHALL use a single "minus" - character without surrounding whitespace. If such separation happens at end of a line, then the "minus" character SHALL be the last characters in the line (no trailing SPACE, and no lines starting with a carried-over minus).

The same markup recommendation (asciidoc or plain-text ASCII preference) applies to contents of the blocks of in-code comments in programmatic source code files and scripts, which may be parsed out into separate text files and rendered or otherwise automatically processed to become man-pages, HTML pages for up-to-date website documentation, etc., by default — unless the chosen and agreed tool set to generate documentation from source code for the whole project dictates another specific markup (JavaDoc, Doxygen, etc. — and such tool and markup should be consistent for all of the project’s code in a specific programming language).

Written documentation intended for consumption in non-plaintext markup (e.g. converted to PDF, MAN or HTML pages) and proposed changes to such documentation SHOULD be inspected in a final processed format by author before committing the pull request: it may happen that escape characters, careful line breaks, etc. in the source markup are needed for the final document to be rendered properly. It is RECOMMENDED that such final format be also checked with a programmatic spell-checker (for example in a desktop word processor program), in order to avoid "typos" and subsequent pull requests to fix them.