Writing Documentation

Documentation is an essential part of any software product.

4 Types of Documentation

This site is an example of Reference documentation.

Where should I put Documentation?

The README

Basic How To Documentation should go into a README file in each repo:

  1. A high level summary of what the code in the repo does (“This code is … “)

  2. Licensing and community information (“This is developed by ONF as a part of the FOO project, and licensed under Apache-2”)

  3. High level dependencies required (“Go version 1.17.x is needed to…”)

  4. Examples of how to build the code (“Run make build to create a binary named …”)

  5. Examples of how to run the code (“The output binary can be found in and run with …”)

  6. How the code is tested (“Your code should pass make test”)

Generally this should be fairly short and easy to reference

Design Documents

Design Documents concern the Why …

One option is to place these in the code repo

Tutorials

Operations Guides

These show a user How to use a project and software. Generally these should be located in a documentation repo, not stored with code.

Project Documentation