Documentation Syntax and Style

Although this wiki is written in Markdown, the documentation itself is written in reStructuredText because we use the Sphinx tool to generate the online HTML documentation.

Links

We prefer using references rather than inline links. This means that the text contains marked up words or phrases that refer to a resource elsewhere. The connection between the text and the resource is defined separately. For example:

The development boards for the Librem 5 are built around the `EmCraft i.MX 8M SoM`_,
a development platform based on the i.MX8 CPU.

.. _`EmCraft i.MX 8M SoM`: https://www.emcraft.com/products/868

These can be defined in the document where they are used, but commonly used resources should be collected in the links.rst file at the root of the repository. Documents that need to refer to these definitions can include them like this:

.. include:: /links.rst

If a link in a document requires generic text, such as in the following example, then the resource should be defined in the same document.

The `latest documentation`_ for Builder describes the `preferred installation`_
method for the IDE.

We don't want to include definitions for "latest documentation" and "preferred installation" in the global collection because they could clash with other uses of these phrases in links elsewhere in the documentation.

Titles

The preferred style is to capitalize verbs ("Editing", "Create"), adjectives ("Large", "New"), nouns ("Board", "Image") but not articles ("the", "a"), conjunctions ("and", "or") and prepositions ("with", "for"). If capitalizing a word makes its meaning unclear, or it refers to a command, then it should be used verbatim (as is) and not capitalized.

This isn't critical but it makes the documentation a bit more consistent.