Documentation Framework

There are 4 types of documentation

  • Tutorials(Learning Oriented)
  • How to guides(Problem Oriented)
  • Explanations/Discussions(Understanding Oriented)
  • Reference(Information Oriented)

Documentation Grid

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.

Source

More Information

Published on: 3rd February, 2021