style-guide.adoc

• pay attention to and follow the existing style

  • standardize whenever possible and formalize conventions here

• images

  • center most and constrain to 80% wide

• exclude optional slashes at ends of hyperlinks

• capitalize product/project names in prose as they appear in upstream’s branding/docs

• capitalize only the first letter of the first word of sections/headers

  • except: follow styling of proper nouns, acronyms, etc.

• lists

  • ordered lists

    • use captals and periods, even if using incomplete sentences

• define jargon and acronym twice:

  • at first appearance, immediately following the term, in parentheses or locale-appropriate delimiters

  • in the glossary

• footnotes

  • don’t use footnotes

• links

  • include links next to or very near context, but try to avoid breaking the flow of text

  • always include typed-out URL, never link text directly

    • this is to ensure consistent appearance across print and electronic versions

  • exclude URL scheme from http(s) links

    • this is handled automatically by asciidoc option hide-uri-scheme

    • https is a safe guess/default (and hopefully people insist on https client-side!)

  • if a link works without www. at the beginning of the domain name, omit it

    • this is bit of a risk: we’re prioritizing shorter links in favor of more reliable links (some websites redirect, adding back www.)

  • if a link works without a SEO slug, omit it

    • example w/slug: https://reddit.com/r/BorgBackup/comments/v3bwfg/why_should_i_switch_from_restic_to_borg/

    • example w/o slug: https://reddit.com/r/BorgBackup/comments/v3bwfg/

    • shorter is better, canonical/permalink is best (if you are forced to choose)

  • use more readable version for cross references whenever possible

    • no: <<_more_about_foss>>

    • yes: <<More about FOSS>>

• use “command line” to refer to a Linux text-based interactive user interface

• use Oxford commas

• use one sentence per line

• shell scripts

  • prefer long form for command line flags, e.g. --attribute instead of -a

  • prioritize portability and maintainability

• release versioning

  • use semver-like major, minor, patch version numbers

• source control

  • commit early and often

  • group logically related changes into single commits

    • consider future maintainers may wish to git revert: try to make that easy for them

  • group a series of related changes in a branch

  • squashing is OK

  • before submitting patches:

    • ensure build passes

  • commit log messages

    • the first line of a commit log message is very important: say precisely what change you made, save the why for the rest

    • use infinitive verb forms, e.g. “add -q quiet option”

    • don’t wrap body text

    • see also:

      • https://mifosforge.jira.com/wiki/spaces/MIFOS/pages/4456742/Commit+Log+Guide

      • https://lore.kernel.org/git/7vr4waoics.fsf@alter.siamese.dyndns.org/

      • https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

  • ChangeLog

    • one entry per release

    • summarize major changes since last release

    • use infinitve forms for “xyz happened” statements

• use shb namespace for document attributes

  • short for “self-hosting book”

  • example: shb-printPDF, used when generating a PDF for printing

• include a trailing slash when referencing folders, e.g. ansible/

• indexing

  • prefer flow index terms over concealed index terms

  • use your gut: index a term when it feels helpful to draw the reader’s attention somewhere to read more about the term

  • don’t worry about indexing every occurence of a particular term — focus on where it is specifically discussed/defined, rather than just used

  • note: indexes are only generated for PDF outputs

• data is plural, use context for singular (e.g. “piece of data”)

• colons: captalize word after? sometimes? TBD

• em dash: omit space before and after