from list to last

readme.md

@@ -27,7 +27,7 @@ Could software documentation:
 How can situated practices inform the process of documenting software?
 And how can situated software inform the process of technical writing?
 
-## Table of Contents (draft)
+# Table of Contents (draft)
 
 ![exploratory documentation aspects + 2 frogmouth birds](img/frogmouth_aspects.jpg)
 
@@ -51,32 +51,48 @@ The critical and theoretical research will be weaved around the actual documenta
     Strategies to share workloads and collaboration
     Strategies to take care of shared piece of software. -->
 
-1.  Coding Contingencies _(2000)_  
+## 1. Coding Contingencies
+
+_(2000)_
+
 Situate software as cultural object and propose documentation as a surface to explore it.
 
-    1. Context around software, besides technicality _(500)_
-        - Refer to software studies
-    2. Introduce issues around software _(1000)_
+### 1.1 Context around software, besides technicality
+
+_(500)_
+
+Refer to software studies
+
+### 1.2 Introduce issues around software
+
+_(1000)_
+
 Outline a map of critical issues related to software culture, grouping them in three main flavours:
 
-        1. Biased and hostile environments
+1. **Biased and hostile environments**
     - Toxic masculinity, encoded chauvinism, western monoculture
-        2. Evergrowing complexity
+2. **Evergrowing complexity**
     - Intimidating learning curve, disproportion of means, mistification
-        3. The universal solution™
+3. **The universal solution™**
     - Techno solutionism, gray tech, ideology
 
-    3. Propose documentation as a surface to address these issues _(500)_
+### 1.3 Propose documentation as a surface to address these issues
+
+_(500)_
+
 1. Welcoming diverse knowledges
 2. Lowering barriers and create entry points
 3. Orientate software in the world
 
-2.  Documentation as an interface _(3000)_  
+## 2. Documentation as an interface
+
+_(3000)_
+
 Aknowledge documentation as crossroad for different actors, as intersection between code, machines, developers, users. Articulate it as a vantage point from where to reason about software.
 
-    0. Define software documentation
+### 2.0 Define software documentation
 
-        - _What is written?_
+_What is written?_
 
 1. From printed manuals to discord servers _(small historical overview)_
 2. Dyataxis framework: Reference, How-to, Guide, Tutorial.
@@ -85,9 +101,9 @@ The critical and theoretical research will be weaved around the actual documenta
 -   rather to a form of care (for users, for software, for context)
 -   in the context of situated software
 
-    1. Welcoming diverse knowledges
+### 2.1 Welcoming diverse knowledges
 
-        - _Who is writing?_
+_Who is writing?_
 
     -   How does development and technical writing interact?
     -   Is the technical writer a subaltern position in the industry of software development?
@@ -95,42 +111,52 @@ The critical and theoretical research will be weaved around the actual documenta
     -   No one wants to write documentation, or pay someone to do it
     -   Documentation as a form of care
 
-        - _Who will read?_  
+_Who will read?_  
 _Who is addressed?_
 
     -   Assuming a certain kind of reader (often male, often white, often with formal education)
-            - Read the feminist manual (Karayanni, 2021)
-            - Programming for the millions (Ullman, 2016)
+    -   _Read the feminist manual_ (Karayanni, 2021)
+    -   _Programming for the millions_ (Ullman, 2016)
 
-    2. Lowering barriers and create entry points
+### 2.2 Lowering barriers and create entry points
 
     - _Who can access?_
     - [welcome.js](https://jamesbridle.com/works/welcome-js) (Bridle, 2016)
-        - Debugging (P5js Education Working Group, 2015)
-        - Wheatering software winter (100R, 2022)
+    - _Debugging_ (P5js Education Working Group, 2015)
 
-    3. Orientate software in the world
+### 2.3 Orientate software in the world
 
-        - _Who is making the software?_
-        - Post-meritocracy manifesto (Ehmke, 2018)
+_Who is making the software?_
 
+-   Post-meritocracy manifesto (Ehmke, 2018)
 -   "We acknowledge the value of all contributors as equal to the value of contributors who are engineers."
 
-        - _How are we making it?_
+_How are we making it?_
+
 -   Patterns of Software (Gabriel, 1996)
 -   Situated Software (Shirky, 2004)
 -   Aesthetic Programming (Geoff & Soon, 2022)
+-   _Wheatering software winter_ (100R, 2022)
 -   Ways of Being (Bridle, 2022)
 
-3.  Situated software requires situated documentation (3000)
+## 3. Situated software requires situated documentation (3000)
+
+### 3.1 Situated software lifecycle. Inner public, outer public.
 
-    -   Situated software lifecycle. Inner public, outer public.
     - Inner public is the target audience of a situated software. The community where it has been developed. _Private public._
     - Outer public is others: different communities that approach to it later on or for different purposes. _Public public._
     - What role plays documentation in these two moments?
-    -   Documenting situated practices as an ongoing process. A recipe in the making.
+
+### 3.2 A recipe in the making.
+
+Documenting situated practices as an ongoing process.
+
     -   Techno-solutionism reversed: are we the solution to our tools' problems?
     -   A praise for partial solutions
-    -   Code as common. Documentation as loose interface between different needs.
+
+### 3.3 Code as common.
+
+Documentation as loose interface between different needs.
+
     -   Situated documentation is tailored on specific needs, and produced from specific perspectives.
     -   How can it resonate with different ones?