Documentation Types

This page explains differences between different types of documentation.

There are three basic types of documentations:

  • tutorials (aka quick start or getting started)
  • topical guides
  • reference (aka API documentation)

None of these three types is a substitute for any other one. They are complementary.

Great blog post about difference between these three basic types is available as Jacobian blog post. Below, we quickly scratch the differences.

Tutorials

Tutorials are like a front door or a shop window. They demonstrate how your project "feels". They're important from marketing point of view.

A great example of tutorials are interactive sessions. See try Ruby as a role model.

Guides

Guides are meat of documentation and they should:

  • be comprehensive,
  • show vast majority of possible options (but should not show all possible options -- that is the task for reference),
  • show how all concepts fit together,
  • answer the question "why?".

References

References should:

  • answer the question "how?".

Reference is the only type of documentation that you could autogenerate from code (i.e. from docstrings), but we don't recommend it.

How-tos

Are step-by-step guides for specific use case. Similar to tutorial, how-tos are the front door and are important from marketing site. Link to how-tos from your marketing site.

Example Applications

Code can be documentation. Example applications and environment are great examples. Some developers start from such example instead of reading documentation. Example apps are also easier and faster to create.

A role model of such examples is braintree.

Cheat sheet

Cheat sheets can contain the basic information about most important concepts from your project.

What is not documentation?