@ -111,6 +111,15 @@ this can happen for several different reasons, two of them apparently at the opp
problems of contents:
expect
- expert, formerly educated reader
- takes for granted the technical level of reader
- takes for granted a specific lexicon,
- refer to a broader context or previous, not explicit references
- see programming for the millions (ullman, 2016)
<!-- Code documentation tends to assume a certain kind of reader. This reader is often thought as similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cut through the precise lingo and esoteric references offered as explanation. Eventually (and in most of the cases) who's reading happen to be someone else. This mismatch transforms entry points into barriers that filter out who can participate to coding. -->
too much technical knowledge is required to read the documentation itself.
the docs results impossible to read, and there is no knowledge one can make out of it if not already educated. not filtering knowledge becomes a filter to who can access it.
@ -118,10 +127,13 @@ programming means building abstractions on top of abstractions, ad libitum. two
one is sequential, from the ground up. see nand to tetris. from logic gates to a programmable comptuer. it gives insights on how a machine works starting from scratch.
<!-- The famous Computer Science course_From NAND to Tetris_ is a full journey exploration to build a programmable computer (and playing Tetris on it) starting from simple logical operations. The series of lessons are organized in a modular way, where every week focuses on an higher level of abstraction, building on the precedent one. [example lessons building up] -->
there are some catches though: this is not a tutorial, but an entire university level course. things are offered in a linear way and in a white cube, where one is supposed to begin at lesson number one, and reach till the end. one is not supposed to jump in in the middle of the course.
many code documentations resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, and so on programming is the perfect rabbit hole because of the depth and complexity of each layer that make up for the digital stack
<!-- Programming is a rabbit hole, and one can wander endlessly searching for where to start from. There is always something more low-level, something to understand before trying to understand the current system you are dealing with. -->
bottom-up / top-down
a different kind of approach is more modelled on the way technology and coding confront us in real life. one often starts from the middle.
@ -139,34 +151,15 @@ sometimes code is about performance, sometimes is about flexibility, sometimes i
2 problems of language:
toxic geek masculinity reinforces stereotypes such as gendered roles in programming, or refuses to acknowledge the participation of diverse identities in the making of software. See gender neutral discussion, racist and discriminatory terms, dude behavior. this is reflected in documentation manuals.
---
- gendered writing and gendered roles
- developer often addressed as he/him
- dude culture and toxic masculinity
- example machism, vvvv twitter-api help patches
- example encoded chauvinism
Code documentation tends to assume a certain kind of reader. This reader is often thought as similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cut through the precise lingo and esoteric references offered as explanation. Eventually (and in most of the cases) who's reading happen to be someone else. This mismatch transforms entry points into barriers that filter out who can participate to coding.
Programming is a rabbit hole, and one can wander endlessly searching for where to start from. There is always something more low-level, something to understand before trying to understand the current system you are dealing with.
The famous Computer Science course _From NAND to Tetris_ is a full journey exploration to build a programmable computer (and playing Tetris on it) starting from simple logical operations. The series of lessons are organized in a modular way, where every week focuses on an higher level of abstraction, building on the precedent one. [example lessons building up]
What is the point?
- nice part:
- understanding of how machines work
- increasing levels of abstraction and complexity
but
- not flexible, really
- learning about technology is way less linear than that
- less teleological for sure
toxic geek masculinity reinforces stereotypes such as gendered roles in programming, or refuses to acknowledge the participation of diverse identities in the making of software. See gender neutral discussion, racist and discriminatory terms, dude behavior. this is reflected in documentation manuals.
- expert, formerly educated reader
- takes for granted the technical level of reader
- takes for granted a specific lexicon,
- refer to a broader context or previous, not explicit references
- see programming for the millions (ullman, 2016)
Historically, technical manuals and software specifications have been addressed to a very specific public of male engineers.
@ -175,18 +168,6 @@ This gendered language comes with an embedded and gendered separation of roles.
As Mara Karayanni argues in _Read The Feminist Manual_, published under Psaroskala Zine, the stubborness against gender neutral language in technical writing is but a pretext for refusing to waiver the priviledge of the male programmer.
- problems of language
- gendered writing and gendered roles
- developer often addressed as he/him
- dude culture and toxic masculinity
- example machism, vvvv twitter-api help patches
- example encoded chauvinism
- a whole range of different people read code documentation!
- again diataxis: different format for different levels
- offer guidance between milions references
- goat meme
```note
@ -195,7 +176,6 @@ A couple of brainstorming paragraphs feel free to skip sorry for the inconvenien
Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers.
