@ -43,10 +43,14 @@ 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.
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.
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.
Daniele Procida proposes a systematic approach to organize this wealth of formats (diataxis.fr, 2017).
Using four main modes
- different documentations for different readers
- different documentations for different readers
- wrap up
- wrap up aka: doc world building not only for newcomers but everyone
```
```
note: below are materials from previous writings
note: below are materials from previous writings
@ -76,11 +80,11 @@ Cuneiform writing and comments. (even though this is cuneiform writing and synta
## Different distances
## Different distances
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.
Who is writing could be the very same developer or someone else. Writings
## Different documentation for different readers
## Different documentation for different readers
Documentation comes in many different forms. Daniele Procida offers a systematic approach to organize this wealth of formats (diataxis.fr, 2017).
Documentation comes in many different forms.
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.
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.
