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

116
readme.md
Unescape Escape View File

@ -27,7 +27,7 @@ Could software documentation:
How can situated practices inform the process of documenting software? How can situated practices inform the process of documenting software?
And how can situated software inform the process of technical writing? 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) ![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 share workloads and collaboration
Strategies to take care of shared piece of software. --> Strategies to take care of shared piece of software. -->
1. Coding Contingencies _(2000)_ ## 1. Coding Contingencies
Situate software as cultural object and propose documentation as a surface to explore it.
1. Context around software, besides technicality _(500)_ _(2000)_
- 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:
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 - Toxic masculinity, encoded chauvinism, western monoculture
2. Evergrowing complexity 2. **Evergrowing complexity**
- Intimidating learning curve, disproportion of means, mistification - Intimidating learning curve, disproportion of means, mistification
3. The universal solution™ 3. **The universal solution™**
- Techno solutionism, gray tech, ideology - 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
1. Welcoming diverse knowledges
2. Lowering barriers and create entry points _(500)_
3. Orientate software in the world
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)_ _(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 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)_ _What is written?_
2. Dyataxis framework: Reference, How-to, Guide, Tutorial.
- Here not focusing on one specific catch-all format 1. From printed manuals to discord servers _(small historical overview)_
- rather to a form of care (for users, for software, for context) 2. Dyataxis framework: Reference, How-to, Guide, Tutorial.
- in the context of situated software
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? - How does development and technical writing interact?
- Is the technical writer a subaltern position in the industry of software development? - 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 - No one wants to write documentation, or pay someone to do it
- Documentation as a form of care - Documentation as a form of care
- _Who will read?_ _Who will read?_
_Who is addressed?_ _Who is addressed?_
- Assuming a certain kind of reader (often male, often white, often with formal education) - Assuming a certain kind of reader (often male, often white, often with formal education)
- Read the feminist manual (Karayanni, 2021) - _Read the feminist manual_ (Karayanni, 2021)
- Programming for the millions (Ullman, 2016) - _Programming for the millions_ (Ullman, 2016)
2. Lowering barriers and create entry points ### 2.2 Lowering barriers and create entry points
- _Who can access?_ - _Who can access?_
- [welcome.js](https://jamesbridle.com/works/welcome-js) (Bridle, 2016) - [welcome.js](https://jamesbridle.com/works/welcome-js) (Bridle, 2016)
- Debugging (P5js Education Working Group, 2015) - _Debugging_ (P5js Education Working Group, 2015)
- Wheatering software winter (100R, 2022)
### 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?_ _How are we making it?_
- Post-meritocracy manifesto (Ehmke, 2018)
- "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?_ ## 3. Situated software requires situated documentation (3000)
- 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.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._ - 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._ - 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? - 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? - Techno-solutionism reversed: are we the solution to our tools' problems?
- A praise for partial solutions - 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. - Situated documentation is tailored on specific needs, and produced from specific perspectives.
- How can it resonate with different ones? - How can it resonate with different ones?

Write Preview
Loading…
Cancel
Save