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

Dating Information

If referring to any relational time basis (“currently”, “now”, etc.), consider putting a parenthetical timeframe to allow that information to be assessed open its currency.

For example, instead of saying:

Currently, FujiNet is available on five platforms.

consider the following alternatives:

As of September 2024, FujiNet is available on five platforms.

or

Currently (September 2024), FujiNet is available on five platforms.

Months and years may be abbreviated (e.g. “Sep 24”) when in parentheses.

Notes

Note

To be revised using these available callout/note styles. - europlus

Important Information/Callouts

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 Markdown 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 text is discouraged.

Author Comments

Sometimes an author would like to comment on the material in the Wiki page without making it “authoritative” information. For example, a comment on the “work in progress” nature of the page, or if something needs filling in.

This can be achieved by a variation of the above Informational Note format by using the following Markdown:

>***NOTE:** This is a comment by the author. - authorname*

which displays as:

NOTE: This is a comment by the author. - authorname

The whole Note is in italic, in addition to the usual callout nature and bold "NOTE:" text, and the author of the note (as there may be several authors on any given page) attributes the note to themself.

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!