kata-containers/Documentation-Requirements.md

• Introduction
• General requirements
• Notes
• Code blocks

Introduction

This document outlines the requirements for all documentation in the Kata Containers project.

General requirements

• All documents are expected to be written in GitHub Flavored Markdown format.
• All documents should have the .md file extension.

Notes

Important information that is not part of the main document flow should be added as a Note in bold with all content contained within block quote:

Note: This is areally important point!

This particular note also spans multiple lines. The entire note should be included inside the quoted block.

If there are multiple notes, bullets should be used:

Notes:

• I am important point 1.

• I am important point 2.

• I am important point n.

Code blocks

This section lists requirements for displaying commands and command output.

The requirements must be adhered to since documentation containing code blocks is validated by the CI system, which executes the command blocks with the help of the doc-to-script utility.

• If a document includes commands the user should run, they MUST be shown in a bash code block with every command line prefixed with $ to denote a prompt:

  
      ```bash
      $ echo "Hi - I am some bash code"
      $ sudo docker run -ti busybox true
      $ [ $? -eq 0 ] && echo "success!"
      ```
  
  

• If a command needs to be run as the root user, it must be run using sudo(8).

  
  $ sudo echo "I'm running as root"
  

• All lines beginning # should be comment lines, NOT commands to run as the root user.

• In the unusual case that you need to display command output, use an unadorned code block (```):

  
      The output of the `ls(1)` command is expected to be:
  
      ```
      ls: cannot access '/foo': No such file or directory
      ```