Documentation
Documentation has two audiences:
Users, who must be able to understand the API
Developers, who must be able to understand the implementation
Documentation components
There is not a single way to document a project, but the following should be included in the project:
Readme
License info
Generated documentation site
Issues tracking
Readme
The readme should give a quick introduction to the project and be included in the project root to be noticed fast.
It is not a manual by itself, but a quick-start guide. After reading it anybody should know what the project is about, who is working on it and where to start if he wants to use or modify it.
Currently the readmes are being divided into the following sections:
Introduction
Features
Documentation
Usage, including prerequisites and installation
How to collaborate
License
License
The license file should use a standard license and be included in the project root to be noticed fast. This tells developers what they can do with the application.
Check a licenses guide:
Recommended licenses:
MIT license for simple projects or examples, meant for a wide use
Apache 2 license for more complex projects, meant for a specific range of users
Generated documentation site
There are services for generates documentation:
And tools for generating documentation:
More details will be given in other chapters.
Issues Tracker
There are several services and applications for the issues tracker.
If using Github, it offers one for every repository.
Some alternatives which require a server:
Diagrams
Visual diagrams are helpful for documentation. These should follow the UML specifications.
Tools for creating diagrams:
Additional information
Last updated
Was this helpful?