@ -45,23 +45,45 @@ Documentation is not just for beginners: it's a code companion. One never stops
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.
```
here a picture of the diataxis scheme
```
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.
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.
## below is messy not real text
```
notes:
- gently reminder that would be nice to have always at least these four modes, but often there is no even one.
- better wrap up to say that docs can reach many different ppl (but maybe will be in the first atm missing section about what do we mean by worlding)
```
```
note: below are materials from previous writings
super wip from now on
```
- lowering barriers and creating entry points
- readme examples
- p5js debug examples
## Welcoming writing
- lowering barriers
- debugging (p5.js education working group, 2015)
- aesthetic programming
- readme examples?
- multiple entry points
- different entries make for different knowledges
- drawings and memes
- welcome.js (bridle, 2016)
## "Natural" reader
- assuming a certain kind of reader - expert - dude
- references:
- programming for the millions (ullman, 2016)
- read the feminist manual (karayanni, 2021 )
---
# Provisional txt dump
## Software without documentation
@ -69,9 +91,7 @@ Software without documentation is invisible. Therefore it is important to docume
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.
---
_bonus caption for images:_
## bonus caption for eventual images
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?)
@ -79,17 +99,11 @@ Software documentation is a defensive mechanism operated from our past selves to
Cuneiform writing and comments. (even though this is cuneiform writing and syntax highlighting)
## Different distances
Who is writing could be the very same developer or someone else. Writings
## Different documentation for different readers
Documentation comes in many different forms.
## Again about diataxis
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.
<!--This could be a nice image to rework the diataxis:-->
This could be a nice image to rework the diataxis:
```
practice receiving tutorial
@ -98,34 +112,6 @@ practice giving how to
theory giving reference
```
The structure of dyataxis is useful to navigate through the different needs of a reader, or through different readers at all.
So who's reading?
## Not for beginners
The structure of diataxis is useful to navigate through the different needs of a reader, or through different readers at all.
Documentation that fails to address its reader can result inaccessible and frustrating.
## who is reading?
- assuming a certain kind of reader - expert - dude
- references:
- programming for the millions (ullman, 2016)
- read the feminist manual (karayanni, 2021 )
## lowering barriers and creting entry points
- lowering barrier
- debugging (p5.js education working group, 2015)
- aesthetic programming
- readme examples?
- Problems with depth (too shallow or too deep)
- multiple entry points
- different entries make for different knowledges
- drawings and memes
- welcome.js (bridle, 2016)
that brings us to --> welcoming different knowledges
