@ -43,21 +43,22 @@ The devil is in the details, and software as well: the translation between human
Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering a software, and return to the references when they need a refresher on the syntax of a particular command. They continuously look at code from multiple distances: close to the source code through lines of comment—ignored by the machine, but much appreciated by fellows developers—or from printed books, along with pages of explanations and use cases.
This tentacular surface can reach a programmer in different moment of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the multitude of shapes documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring colored images. Each format comes with different approaches and intentions, and in response to different needs.
This tentacular surface can reach a programmer in different moment of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the multitude of shapes documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring colored images. Daniele Procida proposes a systematic approach to organize this wealth of formats (diataxis.fr, 2017). His framework focuses on the needs of different kinds of readers: by leveraging between practical and theoretical knowledge it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
Daniele Procida proposes a systematic approach to organize this wealth of formats (diataxis.fr, 2017).
```
here a picture of the diataxis scheme
```
Using four main modes
This system organizes the knowledge around code in a way that tries to meet every user possible. The _tutorial_ offers entry points for the newcomer, while the _explanation_ reveals the core mechanism for the more navigated reader. The _how-to_ teaches how to get the work done, while the _reference_ reports a list of information ready to be consulted. Different documentation for different readers for the same code.
- different documentations for different readers
- wrap up aka: doc world building not only for newcomers but everyone
The diataxis framework doesn't encompass every particular necessity or developer, but its two axis offer a good structure to situate documentation within different context.
