Documentation is fundamental to ensure usability and usefulness of the software. It must be stored along the code, ideally in the
docs folder. Basic documentation should also be included in the README.
Documentation is relevant in many forms, each of which should be addressed for different audiences with varying degree of experience and knowledge.
User documentation: Include a documentation for end users, including e.g.
- API documentation, using OpenAPI standard
Developer documentation: Provide instructions for developers.
- How to set up the environment.
- Dependencies, including
- Supported operating systems
- Required libraries
- External dependencies
- Requirements, e.g. hardware, architecture, CPU, RAM, disk space and network bandwidth.
- How to build the code.
- How to package the code.
Additionally, inline code documentation should be used as appropriate.
Administration documentation: Provide instructions for installation, configuration and maintenance, in particular when running as a daemon (e.g. a micro service).
- Configuration instructions
- Start-up script (e.g. init or systemd)
- Monitoring setup, ideally through a monitoring endpoint