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,43 +51,59 @@ 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)_  
-    Situate software as cultural object and propose documentation as a surface to explore it.
+## 1. Coding Contingencies
 
-    1. Context around software, besides technicality _(500)_
-        - Refer to software studies
-    2. Introduce issues around software _(1000)_
-       Outline a map of critical issues related to software culture, grouping them in three main flavours:
+_(2000)_
 
-        1. Biased and hostile environments
+Situate software as cultural object and propose documentation as a surface to explore it.
+
+### 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**
     - 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. Welcoming diverse knowledges
-        2. Lowering barriers and create entry points
-        3. Orientate software in the world
+### 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
 
-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.
+_(3000)_
 
-    0. Define software documentation
+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.
 
-        - _What is written?_
+### 2.0 Define software documentation
 
-        1. From printed manuals to discord servers _(small historical overview)_
-        2. Dyataxis framework: Reference, How-to, Guide, Tutorial.
+_What is written?_
 
-        - Here not focusing on one specific catch-all format
-        - rather to a form of care (for users, for software, for context)
-        - in the context of situated software
+1. From printed manuals to discord servers _(small historical overview)_
+2. Dyataxis framework: Reference, How-to, Guide, Tutorial.
 
-    1. Welcoming diverse knowledges
+-   Here not focusing on one specific catch-all format
+-   rather to a form of care (for users, for software, for context)
+-   in the context of situated software
 
-        - _Who is writing?_
+### 2.1 Welcoming diverse knowledges
+
+_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 is addressed?_
+_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)
+
+### 2.3 Orientate software in the world
+
+_Who is making the software?_
 
-    3. Orientate software in the world
+-   Post-meritocracy manifesto (Ehmke, 2018)
+-   "We acknowledge the value of all contributors as equal to the value of contributors who are engineers."
 
-        - _Who is making the software?_
-        - Post-meritocracy manifesto (Ehmke, 2018)
+_How are we making it?_
 
-            - "We acknowledge the value of all contributors as equal to the value of contributors who are engineers."
+-   Patterns of Software (Gabriel, 1996)
+-   Situated Software (Shirky, 2004)
+-   Aesthetic Programming (Geoff & Soon, 2022)
+-   _Wheatering software winter_ (100R, 2022)
+-   Ways of Being (Bridle, 2022)
 
-        - _How are we making it?_
-        - Patterns of Software (Gabriel, 1996)
-        - Situated Software (Shirky, 2004)
-        - Aesthetic Programming (Geoff & Soon, 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?