Documentation Framework
There are 4 types of documentation
- Tutorials(Learning Oriented)
- How to guides(Problem Oriented)
- Explanations/Discussions(Understanding Oriented)
- Reference(Information Oriented)
They must be kept distinct from each other - this will make it easier to maintain.
Tutorials
Lessons that take the reader by hand thru a series of steps to complete a project.
- Learning by doing
- Getting started
- Inspiring Confidence
- Repeatability
- Immediate sense of achievement
- Concrete, not abstraction
- Minimum necessary explanation
- No distractions
How to Guides
Guides that take the reader thru the steps required to solve a common problem.
- A series of steps
- A focus on the goal
- Addressing specific question
- No unnecessary explanation
- A little flexibility
- Practical usability over completeness
- Good naming
Reference
Technical descriptions of the machinery and how to operate it.
- Structure
- Consistency
- Description
- Accuracy
Explanations
Explanations that clarify and illuminate a particular topic. This takes a wider view.
- Giving context
- Explaining why
- Multiple examples, alternative approaches
- Making Connections
- No instructions or technical descriptions
If you have some parts of one section in another section, you are lowering the quality of the documentation.