Writing Conventions

Table of Contents

This post serves a few purposes:

Set clear formating choices.
Act as a reference for myself. 🙃
Validate formatting after making changes or updates.

Text Formatting

Bold

Use: Actions or Strong Emphasis

UI Elements: Interactions with interface components like button, menus, and dialog boxes (e.g., "Click the Submit button").
Labels: Identifying information labels, typically followed by a colon or hypen (e.g., Name: or Name –).
Definitions: Sparingly used to introduce an important new term.
Emphasis: Call attention to something important without breaking out to an admonition (e.g. "Do not close the window.").

Italics

Use: References or Weak Emphasis

Titles & Publications: Used for titles of books, reports, articles, journals, etc.
Emphasis:
- A piece of relevant information, but not critical to the main idea (e.g. "Timezones are UTC unless stated otherwise.").
- Sparingly used to add a bit of flavor (e.g., "We had just completed the migration when…").

Line-through

Use: Deprecations or Changes

Acknowledges a change to previous information, statements, or way of thinking.

Underline

Use: Avoided

Easily confused with Hyperlinks.

Admonitions

The following admonitions will be used to provide additional information.

Note	Used to provide additional context or helpful clarification that supports the main content.

Tip	Used to share a practical suggestion that can make the task easier or more effective.

Important

Used to highlight information the reader should pay close attention to in order to avoid confusion or mistakes.

Warning

Used to warn the reader about actions that could lead to minor issues like misconfiguration or unintended results.

Caution

Used to alert the reader to actions that could cause serious problems such as data loss or security risks.

Sidebar Blocks

Title is Optional

Sidebars are used to provide additional information to suppliment the context of the main text.

Collapsible Blocks

I will hide screenshots when they are auxiliary.

Screenshot

Checkout Asciidoctor’s documentation!

I will typically hide the output from examples so it doesn’t clutter the document.

Example 1. Collapsible block inside an example block

ls -lha

Output

total 36K
drwxr-xr-x 18 quinshanley staff  576 Mar 31 10:26 .
drwxr-xr-x 22 quinshanley staff  704 Mar 17 09:24 ..
-rw-r--r--  1 quinshanley staff 6.1K Mar 31 20:21 .DS_Store
drwxr-xr-x  6 quinshanley staff  192 Mar 31 10:26 .direnv
-rw-r--r--  1 quinshanley staff  283 Mar 31 10:26 .envrc
drwxr-xr-x 16 quinshanley staff  512 Mar 30 02:00 .git
drwxr-xr-x  3 quinshanley staff   96 Mar  2 11:51 .github
-rw-r--r--  1 quinshanley staff   10 Mar 28 19:33 .gitignore
-rw-r--r--  1 quinshanley staff    0 Mar 28 19:33 .gitmodules
-rw-r--r--  1 quinshanley staff   93 Mar 28 19:33 ACKNOWLEDGMENTS.adoc
-rw-r--r--  1 quinshanley staff  509 Mar 30 19:49 Makefile
drwxr-xr-x  7 quinshanley staff  224 Mar 31 11:28 bin
drwxr-xr-x  5 quinshanley staff  160 Mar 28 19:33 entrypoint.d
-rw-r--r--  1 quinshanley staff  308 Mar 28 19:33 entrypoint.sh
-rw-r--r--  1 quinshanley staff  569 Mar 28 19:33 flake.lock
-rw-r--r--  1 quinshanley staff  596 Mar 28 19:33 flake.nix
drwxr-xr-x 18 quinshanley staff  576 Mar 31 22:07 site
drwxr-xr-x  3 quinshanley staff   96 Mar 27 20:24 submodules

Horizontal Description List

Used to nicely format a list of descriptors and descriptions.

Title is Optional

Normal Descriptor	This descriptor has no formatting.
Bolded Descriptor	This descriptor is bolded.
Bolded Descriptor	This descriptor is italicized.
`Cmd`+`Shift`+`N`	This descriptor is a keyboard shortcut.

Mermaid Diagrams

graph LR;
A[Lemons]-->B[Lemonade];
B-->C[Profit!]

sequenceDiagram
  Alice->>Bob: Hello
  Bob-->>Alice: Hi