FujiNet Documentation Style Guide

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 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

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

FujiNet

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.

or

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

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

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. 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.

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:

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!

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:

1. This is a Markdown numbered list
   • Which has some sub-lists
   • This is obviously unnumbered
2. 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

3. No need to keep track of numbers
4. If you need to move, add, or delete lines
5. 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!

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 -->

Style guide scratch pad

Note

Stuff I find which I think is worthwhile incorporating into the style guide - feel free to add Markdown code here, just reference back to source page with [[Page title]] link format, just leave this scratch pad as the last section - europlus

Footnotes?

Here is a simple footnote[^1].

A footnote can also have multiple lines[^2].

[^1]: My reference. [^2]: To add line breaks within a footnote, prefix new lines with 2 spaces. This is a second line.

Checklists?

• #739
• https://github.com/octo-org/octo-repo/issues/740
• Add delight to the experience when all tasks are complete 🎉