Documentation Standards

Introduction

The following are the standards to be used by Cacti Group members and Contributes when maintaining the documentation of Cacti or any of its plugins. These standards have also been applied to the Travis CI checker on GitHub.

Reporting corrections / omissions

Please report any errors or corrections on the Cacti Documentation GitHub repository which is located at https://github.com/cacti/documentation/ where all changes can be tracked. Any Pull Requests will be welcome to help speed up changes by allowing the Cacti Group to simply verify the changes are correct before submitting them.

All documentation should be marked as copyright to the Cacti Group. This is done by simply adding the following text to the bottom of the page (including the blank line):


---
<copy>Copyright (c) 2004-2023 The Cacti Group</copy>

Titles

Title Levels

When creating documentation titles, they should:

Failure to follow this will result in an MD001 error during Travis CI checks.

Example 1. Incorrect Markdown for Title Levels

# Welcome

Welcome to us

## Using the software 1.2

To use most functions of our software, navigate the menus

#### Accessing the menus 1.2.1.1

The menus are located at the top of the page ...
Example 2. Corrected Markdown for Title Levels

# Welcome

Welcome to us

## Using the software 1.2

To use most functions of our software, navigate the menus

### Accessing the menus 1.2.1

The menus are located at the top of the page ...

Title Spacing

All titles should be separated with blank lines either side of the title. The only exception to this is if the title is on the first line of the page. They should also have a single space between the hash symbols and text.

Example 3. Incorrect Markdown for Title Spacing

# Welcome
Welcome to us

## Using the software 1.2
To use most functions of our software, navigate the menus
### Accessing the menus 1.2.1
The menus are located at the top of the page ...
Example 4. Correct Markdown for Title Spacing

# Welcome

Welcome to us

## Using the software 1.2

To use most functions of our software, navigate the menus

### Accessing the menus 1.2.1

The menus are located at the top of the page ...

Titles for Captions

Titles for examples, images and tables are the only exception to the Title Level rule. These are normally set to 6 (Six) hash symbols (e.g., ######). The format of the text should be such that it reads the type of caption, a number, full stop, then the description


###### <caption type> <number>. <description>
Example 5. Example of this caption

###### Example 5. Example of this caption

Text

Standard Text

Any text written outside of code blocks must:

Tables

All tables should have a caption applied to them in the style that was listed above.

Lists

All lists should:

Inline Code

Inline code can be included using the single backtick (`) method to produce code-like references. An example of this would be to:

Example 6. Inline Code

use the \`--help\` parameter on the command

Which would produce:


use the --help parameter on the command


Code Blocks

All code blocks must be:

Where possible, it is advised to try and make use of continuation lines (\) so that these are easily readable on any screen.

Example 7. Code Block with Style

```markdown
This is a markdown example, <b> will display <b> not start a bold HTML style
Also ` will actually be displayed not interpreted

The style used on the fenced code block should match the contents of the code block. In the above example, we used markdown as we were displaying a markdown example. The following table is a basic example what is most commonly used in the documentation:

Type Markdown Language Usage
C++ c++ Formats code block as C++
PHP php Formats code block as PHP
SQL sql Formats code block as SQL
Script bash Formats code block as bash script
  sh Formats code block as posix script
Shell console Formats code block as command line example
Markdown markdown Formats code block as Markdown

URLs

All URLs should be formatted in the markdown format and not just inserted directly into the text. The format for this is:

[text for link](https://url/wanted)

Failing to do this will result in MD034 Bare URL used

This would produce: text for link

Horizontal Rules

Horizontal rules should be made using three or more consecutive hyphens on a single line. Again, these should be surrounded by spaces.

Paragraph 1 text

---

Paragraph 2 text

Before testing your changes make sure you add the necessary links to README.md for any new files

Running this script will help you check for any missing links.

bin/check_missing_link.sh

Testing changes

To locally test the changes made to any Markdown document, you will need to have ruby installed and then run:

gem install mdl

If this pre-requisite has already been completed, then you can simply type the following into your shell

cd <cacti_docs>
bin/check_markdown_style.sh

Which will generate the same output that is seen on the Travis CI build status. You should ensure that any reported errors are corrected before submitting your pull request.

Documentation-Standards.md:221: MD031 Fenced code blocks should be surrounded by blank lines
Documentation-Standards.md:230: MD031 Fenced code blocks should be surrounded by blank lines
Documentation-Standards.md:232: MD031 Fenced code blocks should be surrounded by blank lines
Documentation-Standards.md:265: MD031 Fenced code blocks should be surrounded by blank lines
Documentation-Standards.md:268: MD031 Fenced code blocks should be surrounded by blank lines
Documentation-Standards.md:290: MD031 Fenced code blocks should be surrounded by blank lines
Documentation-Standards.md:292: MD031 Fenced code blocks should be surrounded by blank lines
Documentation-Standards.md:161: MD032 Lists should be surrounded by blank lines
Documentation-Standards.md:250: MD032 Lists should be surrounded by blank lines
Documentation-Standards.md:253: MD032 Lists should be surrounded by blank lines
Documentation-Standards.md:256: MD032 Lists should be surrounded by blank lines
Documentation-Standards.md:236: MD033 Inline HTML
Documentation-Standards.md:240: MD033 Inline HTML

Copyright (c) 2004-2023 The Cacti Group