_Documentation as a way to lower barriers & create entry points_
- which software (code related, situated software)
- which documentation (from framework to form of care)
- references:
- diataxis (procida, 2017)
- situated software (shirky, 2004)
contents:
why doc
- software without documentation is invisible
- documenting code from different distances
- not just for beginner
how doc
- different documentations for different readers
- see diataxis
probs
- who is reading?
- not for beginner
props
- lowering barriers and creting entry points
- readme exampless
- p5js debug examples
## Software without documentation
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 it tackles 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 specificities make every piece of code alien and peculiar.
Opening undocumented code feels like being a small 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 some guidance through the bunch of functions and statements that makes software.
These guidelines are helpful when sharing programs with others and 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.
Software documentation is a defensive mechanism operated from our past selves to protect the present and future ones.
Cuneiform writing and comments. (even though this is cuneiform writing and syntax highlighting)
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.
## Different distances
Documentation happens at different distances from code: it can be inserted directly in source with lines of comment that are ignored by the machine, but much appreciated by fellows developers, or it can be printed in books, along with pages and pages of examples and references.
Who is writing could be the very same developer or someone totally different.
Every distance comes with different approaches and intentions, and responds to different needs.
Documentation is a way to make the intentions behind code public.
## Not just for beginners
Documentation is not just for beginners: it's the code companion.
It does not expire first steps.
It affects code continously.
## 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).
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: -->
@ -19,27 +76,34 @@ 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?
The structure of dyataxis is useful to navigate through the different needs of a reader, or through different readers at all.
- who's reading?
So who's reading?
- assuming a certain kind of reader
## Not for beginners
- expert
- dude
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
## lowering barriers and creting entry points
- lowering barrier
- Problems with depth (too shallow or too deep)
- Where to start?
- references:
- welcome.js (bridle, 2016)
- 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
