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?
Basic How To Documentation should go into a README file in each repo:
A high level summary of what the code in the repo does (“This code is … “)
Licensing and community information (“This is developed by ONF as a part of the FOO project, and licensed under Apache-2”)
High level dependencies required (“Go version 1.17.x is needed to…”)
Examples of how to build the code (“Run
make buildto create a binary named …”)
Examples of how to run the code (“The output binary can be found in and run with …”)
How the code is tested (“Your code should pass
Generally this should be fairly short and easy to reference
Design Documents concern the Why …
One option is to place these in the code repo
These show a user How to use a project and software. Generally these should be located in a documentation repo, not stored with code.