FujiNet Documentation Style Guide

NOTE: Early WIP to record some notes on proposed documentation styles. - europlus

Rationale

Whatever form it takes, a consistent style when presenting documentation affords readers a more productive experience when reviewing docs.

The aim of this document is primarily to provide a consistent look and feel, rather than to change an individual author’s “voice”.

As a project by and for the users, it’s important FujiNet documentation authors feel they can present information in their own voice while allowing others to readily consume that information in a recognisable way.

Primary Focus

This document is primarily focused on how to consistently present information relating to the FujiNet project using the GitHub MarkDown implementation in the FujiNet Wiki.

Basics

Important Notes

When presenting a Note, consider it an important callout of information which might otherwise be easily overlooked, or not obvious.

The basic note format in the FujiNet Wiki uses the following MarkDwon code format:

>**NOTE:** This is important information.

which displays as:

NOTE: This is important information.

This layout easily allows Notes to visually stand out from standard text, as a callout to their importance. Bolding and capitalising “NOTE” further highlights the callout.

Further bolding, or the use of italics, can be used to highlight individual words or phrases in the Note, but the use of indiscriminate ALL CAPS, or bolding/italicising of the whole Note is discouraged.

Numbered Lists

MarkDown makes numbered lists super easy - just prepend each line with a number followed by a period.

While you can manually increment the numbers, it is best to just prepend each line with 1. - MarkDown will automatically increment the numbers and this allows easy addition, deletion, or relocation of individual lines.

For example:

1. This is a markdown numbered list
1. No need to keep track of numbers
1. If you need to move, add, or delete lines
1. Markdown takes care of it all
1. This is very simple

displays as:

1. This is a markdown numbered list
2. No need to keep track of numbers
3. If you need to move, add, or delete lines
4. Markdown takes care of it all
5. This is very simple

Now, what happens if we make some changes, like so:

1. This is a markdown numbered list
1. This is very simple
1. No need to keep track of numbers
1. If you need to move, add, or delete lines
1. MarkDown just renumbers every line

we end up viewing this as:

1. This is a markdown numbered list
2. This is very simple
3. No need to keep track of numbers
4. If you need to move, add, or delete lines
5. MarkDown just renumbers every line

Ta-da!