From 942ad1b26c5915484b43ee4293138e1e0e156866 Mon Sep 17 00:00:00 2001 From: km0 Date: Fri, 31 Mar 2023 17:56:46 +0200 Subject: [PATCH] natural reader i hate you --- chapters/01_entry_points.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/chapters/01_entry_points.md b/chapters/01_entry_points.md index 41d11bc..3f84180 100644 --- a/chapters/01_entry_points.md +++ b/chapters/01_entry_points.md @@ -107,45 +107,49 @@ Message in console printed by Bridle to welcome users - source: booktwo.org Documentation that assumes a certain kind of reader can result inaccessible. 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. +a. +When it comes to contents, the reader is often thought similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cutting through the precise lingo and esoteric references offered as explanations. 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. -When it comes to contents, the 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. +When too much technical proficiency is required to even read documentation itself, knowledge results inaccesible and confined in an ivory tower. An important detail to notice here is that this is an antipattern that reinforces the segmentation between who is allowed in and who is not: only previously educated ones can access, while others are kept out. Not filtering information becomes a filter to who can engage with it. Contents need to be curated, that does not mean over-simplified or generalized, but rather made legible. -When too much technical proficiency is required to even read documentation itself, knowledge results inaccesible and confined in an ivory tower. An important detail to notice here is that this is an antipattern, and reinforces the segmentation between who is allowed in and who is not: only previously educated ones can access, while others are kept out. Not filtering information becomes a filter to who can engage with it. -- see programming for the millions (ullman, 2016) +To cultivate legibility is but an easy task, especially when dealing with computer technology: a cards castle of abstractions built on top of other abstractions. -Exploring - - -programming means building abstractions on top of abstractions, ad libitum. +```placeholder +[examples abstraction please] +``` -two different approaches here on how to deal with this intimidating stack of complexity. +These abstractions are more than just metaphors: they are interconnected narrations and entwined plots and main characters at the same time. The purpose of an abstraction is to act as a symbol, as a mentally maneuverable concept free from its technical implementation details. Yet the piling of these structures makes for a dense forest with no clear path to follow in sight. -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. +Take a course such as the one presented by Noam Nisan and Shimon Schocken in _From NAND to Tetris_, where they slowly build a programmable computer able to run the classic game starting from simple logic gates. Here they build one layer after the other, from boolean operations with 0 and 1 to CPUs and registers, from machine language to high level programming. - +Here one can try to unwind the coil and start from scratch, but this approach is best suited to fit a university curriculum, and it's often not real effective when facing real-world problems, with real-world constraints, and real-world circumstances. -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. +A deep understanding of technical systems is admirable and desirable of course, given the insights it can provide on the infrastructures that shapes our everyday lives. But it cannot be the only way of access possible. -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 +And yet, many, many pieces of code documentation resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation 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 +- see proddgramming for the millions (ullman, 2016) 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 _login system_. 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 + + +also piecemeal growth 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 +b. 2 problems of language: