docs/write.rst

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