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