@ -105,9 +105,62 @@ Message in console printed by Bridle to welcome users - source: booktwo.org
### 1.4 "Natural" reader
### 1.4 "Natural" reader
Who writes code documentation tends to assume a certain kind of reader.
documentation that assumes a certain kind of reader can result inaccessible.
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.
this can happen for several different reasons, two of them apparently at the opposite spectrum of the problem: the very contents of documentation and the language with which these contents are exposed
problems of contents:
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.
programming means building abstractions on top of abstractions, ad libitum. two different approaches here on how to deal with this intimidating stack of complexity.
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.
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
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.
programming for advanced beginners series. decoupled tutorial: no specific language, but rather specific case studies to understand practically and first hand. here the series present a practical problem, such as how to code an _hygienic login system_. here like in nand to tetris things are built gradually. here however the process is iterative and circular, instead of linear. implementations are put in place provisionally and then reiterated and developed more, introducing new concepts not as hardcoded procedures but as a result of emerging problems.
the entry points here are multiple as the spokes in a bicycle wheel, as they come from different directions and don't frame the code as a prescriptive and rigid system, but rather as a crafted balance between different forces in play
random access and wandering around
a lesson about code and code documentation can be learned:
sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about everything at the same time. programming means to balance between these different aspects depending on the situation, and depending on who is going to read the code documentation
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.
---
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
