.md

Types of documentation

Roughly speaking, there are three types of documentation for anything programming-related:

1. Reference documentation
2. Conceptual documentation
3. Tutorials

In the sections below, "tooling" will refer to any kind of to-be-documented thing - a function, an API call, a command-line tool, and so on.

Reference documentation

Reference documentation is intended for readers who are already familiar with the tooling that is being documented. It typically follows a rigorous format, and defines things such as function names, arguments, return values, error conditions, and so on. Reference documentation is generally considered the "single source of truth" - whatever behaviour is specified there, is what the tooling should actually do.

Some examples of reference documentation:

• https://nodejs.org/api/querystring.html
• https://doc.rust-lang.org/std/

Reference documentation generally assumes all of the following:

• The reader understands the purpose of the tooling
• The reader understands the concepts that the tooling uses or implements
• The reader understands the relation of the tooling to other tooling

Conceptual documentation

Conceptual documentation is intended for readers who do not yet understand the tooling, but are already familiar with the environment (language, shell, etc.) in which it's used.

Some examples of conceptual documentation:

• http://cryto.net/~joepie91/blog/2016/05/11/what-is-promise-try-and-why-does-it-matter/
• https://hughfdjackson.com/javascript/prototypes-the-short(est-possible)-story/
• https://doc.rust-lang.org/stable/book/the-stack-and-the-heap.html

Good conceptual documentation doesn't make any assumptions about the background of the reader or what other tooling they might already know about, and explicitly indicates any prior knowledge that's required to understand the documentation - preferably including a link to documentation about those "dependency topics".

Tutorials

Tutorials can be intended for two different groups of readers:

1. Readers who don't yet understand the environment (eg. "Introduction to Bash syntax")
2. Readers who don't want to understand the environment (eg. "How to build a full-stack web application")

While I would consider tutorials pandering to the second category actively harmful, they're a thing that exist nevertheless.

Some examples of tutorials:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide
• https://zellwk.com/blog/crud-express-mongodb/
• http://www.freewebmasterhelp.com/tutorials/phpmysql

Tutorials don't make any assumptions about the background of the reader... but they have to be read from start to end. Starting in the middle of a tutorial is not likely to be useful, as tutorials are more designed to "hand-hold" the reader through the process (without necessarily understanding why things work how they work).