The article "What nobody tells you about documentation" details on writing manuals for software. It provides details of different it's components, their intent, content, scope and purpose. This simplifies the process by helping writer have right mindset.
Types of Documentation.
Tutorial.
- Example: README.
- Level: beginner.
- Orientation: to learn.
- Purpose: practical + to study.
* Apply:
- Doorway to your software for any user (setup/installation should be included).
- Multiple tasks (task: short set of steps).
- Contains simple tasks.
- Rewards user with knowledge.
- Must work 100% (makes user confident).
* Avoid:
- Need not use best practice if not required (complicates process).
- Do not explain beyond what is required (makes tutorial long).
How to guides.
- Example: how to print integer.
- Level: intermediate.
- Orientation: goal.
- Purpose: practical + for work.
* Apply:
- Must be working (can be part of test-cases).
- Contains good heading (possible search phrase).
- Should be flexible (include small variation).
* Avoid:
- Should not explain more (link to API documentation).
- Need not have set up or installation steps (intermediate level).
Explanation.
- Example: API docs.
- Level: experienced.
- Orientation: technical details.
- Purpose: theory + to study.
* Apply:
- Should be code based (auto generate is better).
- Example if required (for edge case which is difficult to describe).
- Consistent structure (improves readability).
* Avoid:
- Should not explain about design decision (explain what code does, not why).
- Should not be goal oriented (put it in how to guide).
Reference.
- Example: white paper.
- Level: advanced expert.
- Orientation: to inform.
- Purpose: theory + working.
* Apply:
- Contains design decision (including alternatives).
- Provides historical reasons.
- States good practices.
- Includes discussion or exploration contents.