FujiNet Documentation Style Guide - FujiNetWIFI/fujinet-firmware GitHub Wiki

[!NOTE] Early WIP to record some notes on proposed documentation styles. - europlus, Sep 24

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 to provide that consistent look and feel in the FujiNet docs, while not aiming to change any 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 designed to help FujiNet documentation authors (and/or site editors) to consistently present information relating to the FujiNet project in the FujiNet Wiki using the GitHub Markdown implementation.

GitHub Flavoured Markdown Basics

Formatting Text

The following basic formatting syntax can be used “as-described” in the linked sections of the Basic writing and formatting syntax guide:

References:

You can get more information about Github Flavoured Markdown in the pages listed below.

[!important] Not all Markdown syntax in those pages are available for Wiki pages - see the list at the bottom of the page for known wiki-unimplemented syntax.

Quickstart for writing on GitHub

Basic writing and formatting syntax

GitHub Flavored Markdown Spec

FujiNet House Style Guide

FujiNet, Fujinet, fujinet, FUJINET, #FujiNet...?

FujiNet

Notes

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. The graphical nature 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 (except for [author comments](#author-comments], below).

[!tip] All of the note syntax tags mentioned here are case-insensitive.

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 italics, in addition to the usual callout nature of the Note, and the author of the note (as there may be several authors on any given page) attributes the note to themself.

Other Note Types

GitHub’s Markdown interpreter has some additional note types which can be used to differentiate Notes based on their intent/content:

> [!TIP]
> Helpful advice for doing things better or more easily.

renders as:

[!TIP] Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

renders as:

[!IMPORTANT] Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

renders as:

[!WARNING] Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

renders as:

[!CAUTION] Advises about risks or negative outcomes of certain actions.

Lists

Unnumbered Lists

Github’s Markdown parser allows several types of indicators of unnumbered lists (-, * or +).

[!Note] Each time the list indicator changes, a new list is started.

For example:

* An asterisk Markdown list indicator
* With a second item
- A dash Markdown list indicator starts a new list
- Another dash Markdown list indicator
+ And, while a valid list indicator, changing to a plus starts a new list again
+ Which can be continued
+ As long as you keep using the same indicator

renders as:

An asterisk Markdown list indicator
With a second item

A dash Markdown list indicator starts a new list
Another dash Markdown list indicator

And, while a valid list indicator, changing to a plus starts a new list again
Which can be continued
As long as you keep using the same indicator

[!Note] The difference between in-list and between-list spacing shows the delineation between lists.

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:

This is a Markdown numbered list
No need to keep track of numbers
If you need to move, add, or delete lines
Markdown takes care of it all
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:

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

Ta-da!

Lists and Code Blocks Within Lists

If you wish to have sub-lists, or code blocks within lists, you need to indent to the position of the parent item’s text.

For example:

1. **This is a Markdown numbered list**
   - Which has some sub-lists
   - This is obviously unnumbered
1. This is very simple
   1. As are numbered sub-lists
   1. While maintaining main list numbering
   1. And a useful piece of code, indented
      ```
      ls -la
      ```
   1. And numbering continues
1. No need to keep track of numbers
1. If you need to move, add, or delete lines
1. MarkDown just renumbers every line

* **This is an unnumbered list**
  + With sub-items
  + With the list indicator indented to match the location of the parent item
  + And a code block similarly further indented to match this list item

    ```
    ls -la
    ```
* And then back again

renders as:

This is a Markdown numbered list
- Which has some sub-lists
- This is obviously unnumbered
This is very simple
1. As are numbered sub-lists
2. While maintaining main list numbering
3. And a useful piece of code, indented
```
ls -la
```
4. And numbering continues
No need to keep track of numbers
If you need to move, add, or delete lines
MarkDown just renumbers every line

This is an unnumbered list
- With sub-items
- With the list indicator indented to match the location of the parent item
- And a code block similarly further indented to match this list item
```
ls -la
```
And then back again

Pretty neat!

Time-sensitive or Time-referenced 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.

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

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

Horizontal Rules

These can be inserted by adding three or more dashes in a line, for example:

---

renders as:

If text is on the line immediately before the horizontal rule, it is the identical to the use of the ## Header Level 2 syntax (both place a horizontal rule after the header).

For example:

Just plain old text before a horizontal rule.

---

This will be an (unintended) H2 header
---

renders as:

Just plain old text before a horizontal rule.

This will be an (unintended) H2 header

[!important] For consistency’s sake, please use the ## syntax (see Formatting text > Headings, above) to indicate H2 headers and leave an empty line between text and a horizontal rule.

Markdown comments

While working on a page it is possible to leave hidden comments which do not get displayed with other text.

The format is:

<!-- This content will not appear in the rendered Markdown -->

which renders as:

Oh, hang on, I can’t show what it looks like because it’s hidden! If you want, you can check the Markdown source of this page to confirm the comment is there!

You’ll possibly see quite a few of these comments from me as I work through the documentation pages to fill out this guide and to implement its guidelines. Feel free to add your own, but please use something descriptive and sensible, such as:

<!-- 2024-09-23 [europlus] Introducing Markdown comments to FujiNet documentation -->
<!-- i.e.: -->
<!-- yyyy-mm-dd [username/nickname] Your comment goes here -->

GitHub Flavoured Markdown to Avoid

These are just recommendations, but seem sensible.

Task Lists - these are not “live" task lists, and are therefore prone to abandonment.

GitHub Flavoured Markdown Missing Syntax in Wiki Pages

There’s no point using these: