@ -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.
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
```placeholder
[examples abstraction please]
```
programming means building abstractions on top of abstractions, ad libitum.
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.
<!-- 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] -->
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.
<!-- 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
- 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.
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.
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
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
random access and wandering around
a lesson about code and code documentation can be learned:
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
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
