The 4 types of technical documentation

[loftusa]

I spent some time documenting projects in the past, and when I did I found this talk by Daniele Procida super helpful:
https://www.youtube.com/watch?v=t4vKPhjcMZg

He argues that most software projects which have ineffective documentation have it because different types of documents, catering to different use-cases and audiences, are typically all mixed together.

So, 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.

I think in general naming conventions for documentation should follow this convention.
So,

Documentation --> API
Features --> How-To Guides
Tutorials --> Tutorials

There is currently no Explanations (or discussions). I'm thinking we can pull this section out of the paper as we update/trim for ICLR.

Scikit-learn's documentation does a great job implementing this, I think, as well as Pytorch.