scrib scrib scrib

chapters/00_intro.md

@@ -1,11 +1,12 @@
 TODO:
 
--   groud with a concrete example to make the intro more accessible
+-   groud with a concrete example
--   adjust contingencies paragraph to better address intended audience
+-   adjust second paragraph to better address audience
--   scheme is:
+-   rephrase quotes ?
-    -   Lowering barriers.
+-   outline is:
-    -   Welcoming diverse knowledges.
+    -   Lowering barriers to
-    -   Orientate software in the world.
+    -   Welcoming diverse knowledges for
+    -   Orientate software in the world
 
 ---
 
@@ -21,11 +22,12 @@ It's an approach that helps us to think about software as a cultural object. Som
 
 An object that, in turn, can be used to probe its surroundings. Who is developing? Who is gonna 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 interchangable tools? How long is it supposed to last? How can be fixed if it breaks?
 
-The main focus of this research is to explore software documentation as a surface where this 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 research is to explore software documentation as surface where this 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.
+
+A way to situate programming in specific contexts.
 
 Documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation.
 
-Documentation is a public space that interfaces between the code, the user, the developer, and the world. A space where to welcome different voices: not just engineers, not just experts, not just dudes.
+Documentation is a space that interfaces between the code, the user, the developer, and the world. A space where to welcome different voices: not just engineers, not just experts, not just dudes. A space to aknowledge the massive labor of care besides technicalities, often marginalized by coding culture.
-A space to aknowledge the massive labor of care besides technicalities, often marginalized by coding culture.
 
 A surface that could host principles in close contact with algorithms, letting them entangle and shape each other. A way to orientate our instruments towards "non-extractive relationships, but in the meantime, being accountable for the ones they are complicit with." (A Wishlist for Trans\*feminist Servers, 2022)

chapters/01_interface.md

@@ -1,5 +0,0 @@
-_can documentation be an interface between different knowledges?_
-
--   interface between code, developer, world
--   post meritocracy manifesto
--   trans\*femminist server whishlist

chapters/01_lowering_barriers.md

@@ -0,0 +1,45 @@
+# Who is reading?
+
+-   software documentation
+
+    -   which software (code related, situated software)
+    -   which documentation (from framework to form of care)
+    -   references:
+        -   diataxis (procida, 2017)
+        -   situated software (shirky, 2004)
+
+Documentation comes in many different forms. Daniele Procida offers a systematic approach to organize this wealth of formats (diataxis.fr, 2017). His framework is built at the intersection of two axis: one goes from theoretical to practical knowledges, while the other from study to work. Here _study_ could be read as _learning_ or _understanding_, while _working_ means getting things done. Another powerful couple of synonims is _receiving_ and _giving_: by combining the renamed axis we can get a glimpse of the flow of knoweldge involved in documentation.
+
+<!-- This could be a nice image to rework the diataxis: -->
+
+```
+practice receiving tutorial
+theory receiving explanation
+practice giving how to
+theory giving reference
+```
+
+The structure of dyataxis is useful to navigate through the different needs of a reader, or through different readers at all. So who's reading?
+
+-   who's reading?
+
+    -   assuming a certain kind of reader
+
+        -   expert
+        -   dude
+
+    -   references:
+        -   programming for the millions (ullman, 2016)
+        -   read the feminist manual (karayanni, 2021 )
+
+-   lowering barriers
+
+    -   Problems with depth (too shallow or too deep)
+    -   Where to start?
+    -   references:
+        -   welcome.js (bridle, 2016)
+        -   debugging (p5.js education working group, 2015)
+
+-   multiple entry points
+    -   different entries make for different knowledges
+    -   drawings and memes

chapters/02_welcoming_others.md

@@ -1,4 +1,11 @@
-_can documentation trigger different kinds of economy around software?_
+# Who is writing?
+
+_can documentation be an interface between different knowledges?_
+_trigger different kinds of economy around software?_
+
+-   interface between code, developer, world
+-   post meritocracy manifesto
+-   trans\*femminist server whishlist
 
 -   360 degrees of proximity