@ -50,3 +50,18 @@ Federica Frabetti. “Review of Annette Vee, Coding Literacy.” Computational C
## Parenting is programming, Ian Cheng
Cheng: I wrote “parenting is programming” in the script without any cynicism. I actually believe that is true. Parents quite literally program children, and have an unavoidable influence on their entire life script, their anxiety or their comfort, their sense of trust and mistrust toward the world. But the critical thing most parents forget is that their role as parents, and the stuff they “programmed” into their kids, is scaffolding to get through the early years. But scaffolding is meant to fall away, and most parents don’t know when to let go of their kids, to stop parenting them, to let go of their role. And there isn’t much cultural guidance to help with modeling this type of letting go. In fact, many cultures still require an unhealthy attachment and debt to be constantly connected to one’s parents. I personally have anxiety about not being able to let go when my kids grow up, so I think about this a lot. I guess to answer your question, future education should include modeling how to exit; how to detach from one’s parents, one’s teachers, one’s coddling institutions, and go out and try things and fail and have adventures. Get some scars. Schools should have built-in “anti-school” prep, as counterproductive as that might sound to the big business of schools.
## 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:
```
practice receiving tutorial
theory receiving explanation
practice giving how to
theory giving reference
```
The structure of diataxis is useful to navigate through the different needs of a reader, or through different readers at all.
again versioning tiger ding sun ? --> https://tdingsun.github.io/worlding/
(did already here --> https://hub.xpub.nl/soupboat/~kamo/projects/api-worldbuilding/ )
## Getting started
Reading undocumented code feels like being an 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 guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code.
@ -55,8 +67,6 @@ The same is true for the additional layers of reading~meaning necessary for a pr
## Welcoming writing
<!-- It would be nice to have always at least these four modes, but often there is no even one. -->
note: not sure about this separation below
- lowering barriers
@ -70,11 +80,14 @@ note: not sure about this separation below
- drawings and memes
- welcome.js (bridle, 2016)
The potential of documentation to orientate software in the world clash against some big elephants in the room,and western tech culture should stop keep them in captivity. It would be nice if developers could rely on several kinds of documentation when approaching some code. Unfortunately often there is not even one available.
The potential of documentation to orientate software in the world clashes against some big elephants in the room,and western tech culture should stop keep them in captivity. It would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available.
Writing documentation is demanding. It's more delicate than programming, and require a whole set of skills usually not treasured by the dev community. `(sorry this maybe is an overstatement, hope it is)` A kind of emotional intelligence and sensitivity far to be found in the competitive wastelands of the IT industry. Here no one wants to write documentation, nor hire someone to do it (Gabriel, 1996). As a result, in a world where software thrive, documentation still seems a scarce resource.
Writing documentation is demanding. It's more delicate than programming, and require a whole set of skills usually not treasured by the dev community. _(sorry this maybe is an overstatement, i hope it is)_ A kind of emotional intelligence and sensitivity far to be found in the competitive wastelands of the IT industry.
It's ok, someone could object, every problem that can be asked on Stack Overflow, will eventually be asked in Stack Overflow (paraphrasing Atwood, 2007).
As a result no one wants to write documentation, nor paying someone to do it. (Gabriel, 1996)
and it's amazing to have communities that can solve every problems
but then ppl encoded chauvinism, toxic masculinity, ...
## "Natural" reader
@ -89,7 +102,9 @@ As a result no one wants to write documentation, nor paying someone to do it. (G
## 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 does it tackle the problem to solve.
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 does it tackle the problem to solve.
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.
@ -100,18 +115,3 @@ Being programming slightly different from cycling, people tend to forget what th
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)
## 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:
```
practice receiving tutorial
theory receiving explanation
practice giving how to
theory giving reference
```
The structure of diataxis is useful to navigate through the different needs of a reader, or through different readers at all.
