Software without documentation is invisible. Therefore it is important to document it. Software without documentation tends to slip away, to disappear. Therefore it is important to have some notes on how does it work, how does it tackle the problem to solve.
The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the small specifics of a particular programming language or platform. These specifics make every piece of code alien and peculiar. Tinkering with code is not just knowing by hearth a programming language, but rather having to deal with a lot of different recipes.
Opening undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush, and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software.
These guidelines are helpful when sharing programs with others, as well with future selves. They provide an entry into the messy relationship between developers and machine.
Being programming slightly different from cycling, people tend to forget what their code does, and how did it get there. (Maybe because it doesn't involve muscle memory?)
Documentation can happen at different distances from code: directly in source with lines of comment—ignored by the machine, but much appreciated by fellows developers—or it can be printed in books, along with pages of examples and references.
Who is writing could be the very same developer or someone else. Writings come with different approaches and intentions, and as response to different needs.
Documentation comes in many different forms. Daniele Procida offers a systematic approach to organize this wealth of formats (diataxis.fr, 2017).
His framework is built at the intersection of two axis: one goes from theoretical to practical knowledges, while the other from study to work. Here _study_ could be read as _learning_ or _understanding_, while _working_ means getting things done. Another powerful couple of synonims is _receiving_ and _giving_: by combining the renamed axis we can get a glimpse of the flow of knoweldge involved in documentation.
