kamo
/
thesis
1
2
Fork 0
Code Issues Pull Requests Releases Wiki Activity

from list to last

Browse Source
main
km0 2 years ago
parent 5be0772330
commit 9797d1c492
1 changed files with 89 additions and 63 deletions
Show Stats Download Patch File Download Diff File

152
readme.md
Unescape Escape View File

@ -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?

Write Preview
Loading…
Cancel
Save