You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
46 lines
1.7 KiB
Markdown
46 lines
1.7 KiB
Markdown
2 years ago
|
# Who is reading?
|
||
|
|
|
||
|
|
- software documentation
|
||
|
|
|
||
|
|
- which software (code related, situated software)
|
||
|
|
- which documentation (from framework to form of care)
|
||
|
|
- references:
|
||
|
|
- diataxis (procida, 2017)
|
||
|
|
- situated software (shirky, 2004)
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<!-- This could be a nice image to rework the diataxis: -->
|
||
|
|
|
||
|
|
```
|
||
|
|
practice receiving tutorial
|
||
|
|
theory receiving explanation
|
||
|
|
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?
|
||
|
|
|
||
|
|
- who's reading?
|
||
|
|
|
||
|
|
- assuming a certain kind of reader
|
||
|
|
|
||
|
|
- expert
|
||
|
|
- dude
|
||
|
|
|
||
|
|
- references:
|
||
|
|
- programming for the millions (ullman, 2016)
|
||
|
|
- read the feminist manual (karayanni, 2021 )
|
||
|
|
|
||
|
|
- lowering barriers
|
||
|
|
|
||
|
|
- Problems with depth (too shallow or too deep)
|
||
|
|
- Where to start?
|
||
|
|
- references:
|
||
|
|
- welcome.js (bridle, 2016)
|
||
|
|
- debugging (p5.js education working group, 2015)
|
||
|
|
|
||
|
|
- multiple entry points
|
||
|
|
- different entries make for different knowledges
|
||
|
|
- drawings and memes
|