From 9797d1c4926fc40a9d3e92213d97bed785a0db1b Mon Sep 17 00:00:00 2001 From: Francesco Luzzana Date: Tue, 24 Jan 2023 00:24:46 +0100 Subject: [PATCH] from list to last --- readme.md | 152 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 89 insertions(+), 63 deletions(-) diff --git a/readme.md b/readme.md index 695b03c..3f253fe 100644 --- a/readme.md +++ b/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,86 +51,112 @@ 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 - - Toxic masculinity, encoded chauvinism, western monoculture - 2. Evergrowing complexity - - Intimidating learning curve, disproportion of means, mistification - 3. The universal solution™ - - Techno solutionism, gray tech, ideology +Situate software as cultural object and propose documentation as a surface to explore it. - 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.1 Context around software, besides technicality -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. +_(500)_ - 0. Define software documentation +Refer to software studies - - _What is written?_ +### 1.2 Introduce issues around software - 1. From printed manuals to discord servers _(small historical overview)_ - 2. Dyataxis framework: Reference, How-to, Guide, Tutorial. +_(1000)_ - - 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 +Outline a map of critical issues related to software culture, grouping them in three main flavours: - 1. Welcoming diverse knowledges +1. **Biased and hostile environments** + - Toxic masculinity, encoded chauvinism, western monoculture +2. **Evergrowing complexity** + - Intimidating learning curve, disproportion of means, mistification +3. **The universal solution™** + - Techno solutionism, gray tech, ideology - - _Who is writing?_ +### 1.3 Propose documentation as a surface to address these issues - - How does development and technical writing interact? - - Is the technical writer a subaltern position in the industry of software development? - - Who gets to write, and who is forced to? - - No one wants to write documentation, or pay someone to do it - - Documentation as a form of care +_(500)_ - - _Who will read?_ - _Who is addressed?_ +1. Welcoming diverse knowledges +2. Lowering barriers and create entry points +3. Orientate software in the world - - 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) +## 2. Documentation as an interface - 2. Lowering barriers and create entry points +_(3000)_ - - _Who can access?_ - - [welcome.js](https://jamesbridle.com/works/welcome-js) (Bridle, 2016) - - Debugging (P5js Education Working Group, 2015) - - Wheatering software winter (100R, 2022) +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. - 3. Orientate software in the world +### 2.0 Define software documentation - - _Who is making the software?_ - - Post-meritocracy manifesto (Ehmke, 2018) +_What is written?_ - - "We acknowledge the value of all contributors as equal to the value of contributors who are engineers." +1. From printed manuals to discord servers _(small historical overview)_ +2. Dyataxis framework: Reference, How-to, Guide, Tutorial. - - _How are we making it?_ - - Patterns of Software (Gabriel, 1996) - - Situated Software (Shirky, 2004) - - Aesthetic Programming (Geoff & Soon, 2022) - - Ways of Being (Bridle, 2022) +- 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 -3. Situated software requires situated documentation (3000) +### 2.1 Welcoming diverse knowledges - - 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. - - 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. - - Situated documentation is tailored on specific needs, and produced from specific perspectives. - - How can it resonate with different ones? +_Who is writing?_ + + - How does development and technical writing interact? + - Is the technical writer a subaltern position in the industry of software development? + - Who gets to write, and who is forced to? + - No one wants to write documentation, or pay someone to do it + - Documentation as a form of care + +_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) + +### 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) + +### 2.3 Orientate software in the world + +_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?_ + +- 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.1 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? + +### 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 + +### 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?