thesis/rug/old_readme.md

# Worlding and Software

How do you choose to learn 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)

![exploratory documentation aspects + 2 frogmouth birds](img/frogmouth_aspects.jpg)

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

## 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

How do you choose a particular programming language, a coding paradigm, a development environment, an infrastructure where to run the code, and so on? These are not just technical choices, but rather coding contingencies.

Personal decisions, trending technologies, curiosity and boredom, to name a few. A talk on esolangs as form of frugality, a collegue passionate about live coding that drags you to an algorave night, a crypto-boyfriend, the tech stack of a company, a drastic turn of events, etc. etc.

These contingencies are situated in contexts.  
Programming then is not just sharing code, but sharing context.  
It's providing a point of view and a perspective to look at the world, before attempting to get some grip onto it with a script.

-   References to software studies
-   _(500)_

### 1.2 Introduce issues around software

![three spoonbills](img/spoonbils.jpg)

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

-   _(1000)_

### 1.3 Propose documentation as a surface to address these issues

1. Welcoming diverse knowledges
2. Lowering barriers and create entry points
3. Orientate software in the world

-   _(500)_

## 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

-   _(750)_

### 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
-   _(750)_

### 2.2 Lowering barriers and create entry points

_Who can access?_  
_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)

-   [welcome.js](https://jamesbridle.com/works/welcome-js) (Bridle, 2016)
-   _Debugging_ (P5js Education Working Group, 2015)

-   _(750)_

### 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)

-   _(750)_

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

-   _(1000)_

### 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

-   _(1000)_

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

-   _(1000)_

---

# Yet another thesis outline

## 0. Intro - Coding contingencies
_750_

## 1. Who is reading?
_2000_

The first chapter focuses on code documentation as publishing surface. Who is welcome, who is addressed, and who is left out.

Documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation. By reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives.

__Sections:__   

1. Getting started
2. Code companion
3. Welcoming writing
4. Natural readers

## 2. Who is writing?
_2000_

The second part explores documentation as a crossroads, where different knowledges meet in the making of software.

Documentation is a space that interfaces between the code, the user, the developer, and the world. A space where to welcome different voices: not just engineers, not just experts, not just dudes. A space to acknowledge the massive labor of care besides technicalities, often marginalized by coding culture.

__Sections:__

A section that focuses on who is writing the software, but not just the code. From software as inherently collaborative practice to the post-meritocratic manifesto.

A section about who is writing documentation, and how. Different strategies to approach it, from different knowledges. `wip`

## 3. Hello Worlding 
_2000_

The third section is focused on worlding, and the relation between code, documentation practices and political aesthetic.

Here documentation is seen as a surface that could host principles in close contact with algorithms, letting them entangle and shape each other. A way to orientate our instruments towards "non-extractive relationships, but in the meantime, being accountable for the ones they are complicit with." (A Wishlist for Trans\*feminist Servers, 2022)

__Sections:__  

A first part of theoretical examples of technology and worlding: Trans\*feminist Servers, Zach Blas, Tiger Ding Sun, James Bridle, Soon and Geox, Richard Gabriel.

A second part of case studies. The soupboat. Avantwhatever.net. Queer Motto API. The Screenless Office. The uxn ecosystem. `list wip`

## 4. Outro
_750_