Types of documentation and when to use them

Why document projects?

• Quickly get users started
• Show how to use the software
• Explain concepts behind the software
• Describe internal machinery of a project

Types of documentation

Documentation serves different goals, therefore there are different types:

• Tutorials: learning-oriented, allows the newcomer to get started
• How-to guides: goal-oriented, shows how to solve a specific problem
• Explanation: understanding-oriented, explains a concept
• Reference: information-oriented, describes the machinery

README file: (how-to guide)

• First thing a user/collaborator sees
• Contains basic setup instructions and information about the project

In-code documentation (reference)

• Technical documentation in the code
• For example # comments

API reference (reference)

• API reference: detailed description of how each function/class in the code can be used