diff --git a/chapters/01_entry_points.md b/chapters/01_entry_points.md index a5baad7..8b30fd6 100644 --- a/chapters/01_entry_points.md +++ b/chapters/01_entry_points.md @@ -4,7 +4,7 @@ Documentation that assumes a certain kind of reader can result inaccessible. The recipient 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. -Whenever too much technical proficiency is required to even read documentation itself, knowledge results inaccesible and confined in the 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. +Whenever too much technical proficiency is required to even read documentation itself, knowledge results inaccesible, and confined in the 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. ![Structured in six columns: system, processing, memory, storage, networking, human interface. Organized with seven depth: from user space interfaces down to virtual, bridges, functional, devices control, hardware interfaces, electronics.](../img/kernel.png "Linux kernel map.") diff --git a/chapters/02_backdoors.md b/chapters/02_backdoors.md index b7c6a9d..6be3f99 100644 --- a/chapters/02_backdoors.md +++ b/chapters/02_backdoors.md @@ -5,7 +5,7 @@ How do you choose a particular programming language, a coding paradigm, a development environment, an infrastructure where to run the code, and so on? These are not just technical choices, but rather coding contingencies. -The IT class in a public school. The job requirements for working in a tech company. An Arduino board received as gift for birthday. A colleague passionate about experimental music that drags you to a live coding concert. +It may depends on the IT program in a public school, on the job requirements for working in a tech company, an Arduino board received as gift for birthday, or a colleague passionate about experimental music that drags you to a live coding concert. These contingencies are situated in specific contexts. @@ -13,9 +13,9 @@ Programming then is not just sharing code, but sharing context. A significant st It's an approach that helps us to think about software as a cultural object. Something "deeply woven into contemporary life –economically, culturally, creatively, politically– in manners both obvious and nearly invisible." (Fuller, Manovich and Wardrip-Fruin, 2009), and not just as technical tool existing in a vacuum. -An object that, in turn, can be used to probe its surroundings. Who is developing? Who is going to use it? Who is paying for it and why? How is it structured? It is a big and centralized system or a loose collection of small and interchangeable tools? How long is it supposed to last? How can be fixed if it breaks? +Code as an object that, in turn, can be used to probe its surroundings. Who is developing? Who is going to use it? Who is paying for it and why? How is it structured? Is it a big and centralized system, or a loose collection of small and interchangeable tools? How long is it supposed to last? How it can be fixed if it breaks? -The main focus of this chapter is to explore software documentation as a surface where these kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. +The main focus of this chapter is to explore software documentation as a surface where these kinds of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. A way to situate programming in specific contexts, but also to inject our contexts into programming practices. Hence the idea of code documentation as a backdoor: a passage to infiltrate software culture, to change things from the inside and create more entry points.