You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
163 lines
5.6 KiB
Markdown
163 lines
5.6 KiB
Markdown
TODO: a file where to keep references
|
|
|
|
# Worlding and Software
|
|
|
|
|
|
|
|
How do you chose a particular programming language, a coding style, a development environment and ecosystem, an infrastructure where to run the code, and so on?
|
|
|
|
These are **not just technical choices**, but rather coding contingencies.
|
|
|
|
These contingencies are situated in precise economical, cultural, creative, political, and technical contexts. Programming then is not just sharing code, but sharing context. It's providing a perspective to look at the world before attempting to get some grip onto it with a script.
|
|
|
|
How to offer a point of view through the lens of software?
|
|
Who get to participate in this process of making meaning?
|
|
How to create a discourse for the code to inhabit?
|
|
How to stretch the affordances of code, besides technicality, marketing, and advertisement?
|
|
|
|
## Enter documentation
|
|
|
|
Could software documentation:
|
|
|
|
0. be a mean to explore these contingencies?
|
|
1. be an ideal surface to build worlds?
|
|
2. be an interface between different knowledges?
|
|
3. be a device to trigger different kinds of economy around situated software?
|
|
|
|
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)
|
|
|
|
|
|
|
|
The critical and theoretical research will be weaved around the actual documentations, in order to create a discourse and annotate the development of this practice. ???
|
|
|
|
<!--
|
|
Who can access it?
|
|
Where is the documentation hosted?
|
|
|
|
2. **Tone and style**
|
|
|
|
How to make documentation more accessible?
|
|
How to create multiple entry points in a complex topic?
|
|
How to address different kind of users, and not just a generic one?
|
|
How to orientate software in the world?
|
|
|
|
- Documentation as an interface between different knowledges
|
|
|
|
3. **Susteinability**
|
|
How to face the lack of resources when approaching technical writing?
|
|
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.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**
|
|
- Intimidating learning curve, disproportion of means, mistification
|
|
3. **The universal solution™**
|
|
- Techno solutionism, gray tech, ideology
|
|
|
|
### 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)_
|
|
|
|
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.
|
|
|
|
### 2.0 Define software documentation
|
|
|
|
_What is written?_
|
|
|
|
1. From printed manuals to discord servers _(small historical overview)_
|
|
2. Dyataxis framework: Reference, How-to, Guide, Tutorial.
|
|
|
|
- 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
|
|
|
|
### 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?
|
|
- 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?
|