In 2017, Daniele Procida presented What nobody tells you about documentation 1 at PyCon Australia. In his talk, he argues most software projects have ineffective documentation because different types of documents, catering to different use-cases and audiences, are typically all mixed together.

He explains that what we call documentation is fundamentally not one thing, but four related, yet different things:

  • Tutorials, which are learning-oriented, practical steps.
  • How-to guides, which are task-oriented, practical steps.
  • Technical references, which capture information-oriented, theoretical knowledge.
  • Explanations (or discussions), which capture understanding-oriented, theoretical knowledge.

The four types of documentation laid out in a 2 by 2 grid

Daniele argues that to have effective and clear technical documentation, content should be structured explicitly around these four types, all kept separate and distinct from each other.

Since his talk in 2017, he has captured these lessons into the Diátaxis Framework. It has been adopted by numerous projects and organizations, including BBC News Labs, Canonical, Cloudflare, Django, Gatsby and ING Bank, to name but a few.

  1. He also wrote an article covering the same content as his talk, available in PDF format at https://doc.callmematthi.eu/static/webArticles/What%20nobody%20tells%20you%20about%20documentation.pdf ↩︎