From cf9d932152de60e092a32cf66755cc4edf569ea4 Mon Sep 17 00:00:00 2001 From: km0 Date: Sat, 25 Mar 2023 23:31:21 +0100 Subject: [PATCH] reorder natural reader --- chapters/01_entry_points.md | 56 ++++++++++++------------------------- 1 file changed, 18 insertions(+), 38 deletions(-) diff --git a/chapters/01_entry_points.md b/chapters/01_entry_points.md index 1d33063..a5b4bf0 100644 --- a/chapters/01_entry_points.md +++ b/chapters/01_entry_points.md @@ -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) + + + 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. + + 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. @@ -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. -Who is going to read this piece of documentation? Target to reach vs public to create