From 0f6311ddf36857b9770fd65b06503cf731236d87 Mon Sep 17 00:00:00 2001 From: "kam (from the studio)" Date: Wed, 8 Feb 2023 19:36:54 +0100 Subject: [PATCH] 01 --- chapters/01_who_is_reading.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/chapters/01_who_is_reading.md b/chapters/01_who_is_reading.md index a7babba..50d198b 100644 --- a/chapters/01_who_is_reading.md +++ b/chapters/01_who_is_reading.md @@ -49,21 +49,15 @@ This tentacular surface can reach a programmer in different moment of their life This system organizes knowledge around code in a way that tries to meet every user possible. _Tutorials_ offer entry points for the newcomers, while _explanations_ reveal core mechanisms for more navigated readers. _How-to guides_ teach how to get the work done, while _references_ report lists of information ready to be consulted. Different documentations for different readers for the same code. -A text that fails to address who's reading can result inaccessible and frustrating. Although the Diataxis framework doesn't encompass every particular situation, its two axis offer a good structure to situate documentation within different perspectives. This turns out to be really helpful in the process of writing, as a way to fine tune tones and modulate the amount of shared info. +A text that fails to address who's reading can result inaccessible and frustrating. Although the Diataxis framework doesn't encompass every particular situation, its structure offers good aid to situate documentation within different perspectives. This turns out to be really helpful in the process of writing, as a way to fine tune tones and modulate the nature of shared info. -The same is true for the additional layers of reading~meaning necessary for a process of world building. Enchanting software with political aesthetic (Ranciérre read through Soon and Cox, 2020) requires to operate at different scales. Public and private dimensions, within both technical and social framework. +The same is true for the additional layers of reading~meaning necessary for a process of world building. Enchanting software with political aesthetic (Ranciérre through Soon and Cox, 2020) requires to operate at different scales. Within both public and private dimensions, and technical and social frameworks. With a workshop for example, it is possible to meet face to face. Here togetherness can glue technicalities as a paratext, questioning reproduction of knowledge and its power dynamics. (See for example Feminists Federating, mara karagianni, ooooo, nate wessalowski, vo ezn in Toward a Minor Tech - A peer reviewed Newspaper vol 12) (Note that the opposite effect is also true, with technicalities as paratext conditioning how people be together) -``` -notes: -- gently reminder that would be nice to have always at least these four modes, but often there is no even one. -- better wrap up to say that docs can reach many different ppl (but maybe will be in the first atm missing section about what do we mean by worlding) -``` +## Welcoming writing -``` -super wip from now on -``` + -## Welcoming writing +note: not sure about this separation below - lowering barriers @@ -76,12 +70,18 @@ super wip from now on - drawings and memes - welcome.js (bridle, 2016) +The potential of documentation to orientate software in the world clash against some big elephants in the room,and western tech culture should stop keep them in captivity. It would be nice if developers could rely on several kinds of documentation when approaching some code. Unfortunately often there is not even one available. + +Writing documentation is demanding. It's more delicate than programming, and require a whole set of skills usually not treasured by the dev community. _(sorry this maybe is an overstatement, i hope it is)_ A kind of emotional intelligence and sensitivity far to be found in the competitive wastelands of the IT industry. + +As a result no one wants to write documentation, nor paying someone to do it. (Gabriel, 1996) + ## "Natural" reader - assuming a certain kind of reader - expert - dude - references: - programming for the millions (ullman, 2016) - - read the feminist manual (karayanni, 2021 ) + - read the feminist manual (karagianni, 2021 ) ---