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

readme update and a new cover

Browse Source
main
km0 2 years ago
parent a9dc4aa2d7
commit dfe53ec555
6 changed files with 258 additions and 149 deletions
Show Stats Download Patch File Download Diff File

208
carpet/old_readme.md
Unescape Escape View File

@ -0,0 +1,208 @@
# 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_

19
chapters/00_intro.md
Unescape Escape View File

@ -19,13 +19,15 @@ It's an approach that helps us to think about software as a cultural object. Som
An object that, in turn, can be used to probe its surroundings. Who is developing? Who is gonna use it? Who is paying for it and why? How is it structured? It is a big and centralized system or a loose collection of small and interchangeable tools? How long is it supposed to last? How can be fixed if it breaks? An object that, in turn, can be used to probe its surroundings. Who is developing? Who is gonna use it? Who is paying for it and why? How is it structured? It is a big and centralized system or a loose collection of small and interchangeable tools? How long is it supposed to last? How can be fixed if it breaks?
The main focus of this research is to explore software documentation as surface where this kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. The main focus of this research is to explore software documentation as a surface where these kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source.
A way to situate programming in specific contexts. A way to situate programming in specific contexts.
The first chapter focuses on documentation as publishing surface. Who's reading, who is addressed, and what could be done differently. The first chapter focuses on documentation as publishing surface. Who is reading, 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. It reaches not only beginners, but experienced programmers as well. It affects thinking about software continuously, and from different perspectives. 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.
`[but who's left out ...]`
The second part frames documentation as a crossroads, where different knowledges meet in the making of software. The second part frames documentation as a crossroads, where different knowledges meet in the making of software.
@ -35,15 +37,12 @@ The third section is focused on worlding, and the relation between code, documen
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) 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)
## Software documentation ### Software documentation
The concepts of worlding, political aesthetic, and critical thinking can be applied to all sorts of technical manuals. However, the approaches and methods explored in this thesis are mostly informed by practices related to code documentation. While reading, please bind the terms software, application, program, etc. to code. Software documentation? Code documentation. The perspective of this thesis is more aligned to the docs for [ImageMagick](https://imagemagick.org/script/command-line-processing.php), than to the ones for [GIMP](https://www.gimp.org/docs/). The concepts of worlding, political aesthetic, and critical thinking can be applied to all sorts of technical manuals. However, the approaches and methods explored in this thesis are mostly informed by practices related to code documentation. While reading, please bind the terms software, application, program, etc. to code. Software documentation? Code documentation. The perspective of this thesis is more aligned to the docs for [ImageMagick](https://imagemagick.org/script/command-line-processing.php), than to the ones for [GIMP](https://www.gimp.org/docs/).
## For developers ### For developers
Another term to democratize here is _developer_.
By stripping down every trace of professionalism and formal education, let's agree that a developer is someone who tinkers with code. No matter at which level, nor distance, nor experience. No matter if it is for work, for fun, for study. No matter if one is actively involved in the development of a tool, or comes from the user perspective. Ellen Ulman writes that programming is a disease, but the situation is even worse: code is contagious material, touch it once and you are a developer. Another term to democratize (_dismantle?_) here is _developer_.
`potential caption for image` By stripping down every trace of professionalism and formal education, let's agree that a developer is someone who tinkers with code. No matter at which level, nor distance, nor experience. No matter if for work, for fun, for study. No matter if one is actively involved in the development of a tool, or comes from the user perspective. Ellen Ulman writes that programming is a disease, but the situation is even worse: code is contagious material, touch it once and you are a developer.
_Who is a developer? One who programs for a living or one who lives for programming? (based)_

25
chapters/01_who_is_reading.md
Unescape Escape View File

@ -1,6 +1,6 @@
# Who is reading # Who is reading
_why documentation as a surface to build worlds around software?_ _documentation as a surface to build worlds around software?_
_docs to lower barriers and create entry points_ _docs to lower barriers and create entry points_
``` ```
@ -10,8 +10,7 @@ a surface to build worlds?
political of the software political of the software
yes because yes because
it's often first thing one reads when approaching software - see getting started it's often first thing one reads when approaching software - see getting started it's consulted not just from beginner, but also experienced users - see a code companion
it's consulted not just from beginner, but also experienced users - see a code companion
yes but yes but
it should be less hostile - see welcoming writing it should be less hostile - see welcoming writing
@ -37,7 +36,7 @@ again versioning tiger ding sun ? --> https://tdingsun.github.io/worlding/
Reading undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code. Reading undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code.
At the very first encounter with a new script, details about its source code are unknown. Programming is a play _in medias res_, and documentation acts the role of narrator. Describing how functions are stitched together, or an algorithm is implemented, it sets the stage for developers to participate. Showing the different steps of a program and how they are connected, it offers entry points for interventions. At the very first encounter with a new script, details about its source code are unknown. Programming is a play _in medias res_, and documentation acts as narrator. Describing how functions are stitched together, or an algorithm is implemented, it sets the stage for developers to participate. Showing the different steps of a program and how they are connected, it offers entry points for interventions.
For example [Vue.js](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle-diagram), a popular library for building web user interfaces, explains with a diagram the lifecycle of its components: at which moment data are received from a server, at what point an element is rendered on screen, and when it will disappear. What at the beginning feels like magic, gradually appears more clear. Presenting a structure means also presenting a way to reason about it. The reader gains some understanding and agency over the tools they are about to use. For example [Vue.js](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle-diagram), a popular library for building web user interfaces, explains with a diagram the lifecycle of its components: at which moment data are received from a server, at what point an element is rendered on screen, and when it will disappear. What at the beginning feels like magic, gradually appears more clear. Presenting a structure means also presenting a way to reason about it. The reader gains some understanding and agency over the tools they are about to use.
@ -59,7 +58,7 @@ This system organizes knowledge around code in a way that tries to meet every us
A text that fails to address who's reading can result inaccessible and frustrating. Although the Diataxis framework doesn't encompass every particular situation, its structure offers good aid to situate documentation within different perspectives. This turns out to be really helpful in the process of writing, as a way to fine tune tones and modulate the nature of shared info. A text that fails to address who's reading can result inaccessible and frustrating. Although the Diataxis framework doesn't encompass every particular situation, its structure offers good aid to situate documentation within different perspectives. This turns out to be really helpful in the process of writing, as a way to fine tune tones and modulate the nature of shared info.
The same is true for the additional layers of reading~meaning necessary for a process of world building. To enchant software with political aesthetic (Ranciérre through Soon and Cox, 2020) is required to operate at different scales. Within both public and private dimensions, with technical and social frameworks. During a workshop for example, people meet face to face. Here togetherness can glue technicalities as a paratext, questioning reproduction of knowledge and its power dynamics. (See for example _Feminists Federating_, mara karagianni, ooooo, nate wessalowski, vo ezn in Toward a Minor Tech - A peer reviewed Newspaper vol 12, 2023) (Note that the opposite effect is also true, with technicalities as paratext conditioning how people are together) The same is true for the additional layers of meaning necessary for a process of world building. To enchant software with political aesthetic (Ranciérre through Soon and Cox, 2020) is required to operate at different scales. Within both public and private dimensions, with technical and social frameworks. During a workshop for example, people meet face to face. Here togetherness can glue technicalities as a paratext, questioning reproduction of knowledge and its power dynamics. (See for example _Feminists Federating_, mara karagianni, ooooo, nate wessalowski, vo ezn in Toward a Minor Tech - A peer reviewed Newspaper vol 12, 2023) (Note that the opposite effect is also true, with technicalities as paratext conditioning how people are together)
## Welcoming writing ## Welcoming writing
@ -73,13 +72,13 @@ It's ok, someone could argue, every question that can be asked on Stack Overflow
But it's not rare for these places to feel unwelcoming, or even hostile. In 2018, Stack Overflow publicly admitted that there was a problem concerning their userbase. The space felt unfriendly for _outsiders_, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018). But it's not rare for these places to feel unwelcoming, or even hostile. In 2018, Stack Overflow publicly admitted that there was a problem concerning their userbase. The space felt unfriendly for _outsiders_, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018).
For years there have been discussions on the platform about tone. At the question _"Should 'Hi', 'thanks', taglines, and salutations be removed from posts?"_, one of the founders of Stack replied with a [RegEx](https://meta.stackexchange.com/a/93989) to filter automagically what some of the experienced users perceived as noise. This _regular expression_, a way to target specific text patterns in programming, started then to be silently applied to every query sent to the website, trimming out etiquette and leaving just technicalities. For years there have been discussions on the platform about tone. At the question _"Should 'Hi', 'thanks', taglines, and salutations be removed from posts?"_, one of the founders of Stack replied with a [RegEx](https://meta.stackexchange.com/a/93989) to filter _automagically_ what some of the experienced users perceived as noise. This _regular expression_, a way to target specific text patterns in programming, started then to be silently applied to every query sent to the website, trimming out etiquette and leaving just technicalities.
Far from being just an isolated problem, this crudity is deeply embedded in the IT discourse, soaking through technical writings as well. The denigrating expressions of superiority in matters concerning programming that Marino calls _encoded chauvinism_ (Marino, 2020) constitute the main ingredient in the brew of toxic geek masculinity. _Real programmers_ don't use this code editor. _Real programmers_ don't use this programming language. _Real programmers_ don't care about others feelings. Etc. Far from being just an isolated problem, this crudity is deeply embedded in the IT discourse, soaking through technical writings as well. The denigrating expressions of superiority in matters concerning programming that Marino calls _encoded chauvinism_ (Marino, 2020) constitute the main ingredient in the brew of toxic geek masculinity. _Real programmers_ don't use this code editor. _Real programmers_ don't use this programming language. _Real programmers_ don't care about others feelings. Etc.
Ellen Ullman accounts on the emotional dumbness of her _real programmers_ colleagues give an insight of a problematic behavior, first intercepted and then capitalized by the IT industry. _"In meetings, they behave like children. They tell each other to shut up. The call each other idiots. They throw balled-up paper. One day, a team member screams at his Korean colleague, 'Speak English!' (A moment of silence follow this outburst, at least.)"_ (Ullman, 1997; 2017) Ellen Ullman accounts on the emotional dumbness of her _real programmers_ colleagues give an insight of a problematic behavior, first intercepted and then capitalized by the IT industry. _"In meetings, they behave like children. They tell each other to shut up. The call each other idiots. They throw balled-up paper. One day, a team member screams at his Korean colleague, 'Speak English!' (A moment of silence follow this outburst, at least.)"_ (Ullman, 2017)
Programming means to deal with picky stubborn machines that don't overlook a single typo. It requires a high tolerance for failure. It is frustrating. But to project this frustration onto other users, as in the `Read The Fucking Manual` response to a request for help, it's a kind of negative solidarity (Fisher, 2013) that poses serious barriers to participation in the making of software. Programming means to deal with picky stubborn machines that don't overlook a single typo. It requires a high tolerance for failure. It is frustrating. But to project this frustration onto other users, as in the `Read The Fucking Manual` response to a request for help, it's a form of negative solidarity (Fisher, 2013) that poses serious barriers to the participation in the making of software.
Instead... Instead...
@ -96,11 +95,11 @@ Instead...
- programming for the millions (ullman, 2016) - programming for the millions (ullman, 2016)
- read the feminist manual (karagianni, 2021 ) - read the feminist manual (karagianni, 2021 )
- bro culture ? ? ?
(could be the transition from previous section)
(could be the example with evvvvil help patches)
vvvv is a visual programming language that offers an agile approach to prototyping, adoperated especially in the context of interaction design. It's focused on rapid and iterative work of fine tuning, necessary when dealing with real time inputs, such as sensors, live data, or human interaction.
- bro culture ? ? ? (could be the transition from previous section) (could be the example with evvvvil help patches)
vvvv is a visual programming language that offers an agile approach to prototyping, adoperated especially in the context of interaction design. Here agile means rapid, but also flexible, but also simplified: it grants an iterative work of fine tuning, necessary when dealing with real time inputs, such as sensors, live data, or human interaction.
vvvv is a visual programming language vvvv is a visual programming language
used esp with interaction design used esp with interaction design
@ -111,4 +110,4 @@ help patches
- manuals often address just male developers - manuals often address just male developers
- often documentation doesn't offer entry points for beginners, or a sense of direction - often documentation doesn't offer entry points for beginners, or a sense of direction, this esp a problem with hypertexts

BIN
cover.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 263 KiB

After

Width:  |  Height:  |  Size: 62 KiB

BIN
img/old_cover.jpg
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 263 KiB

155
readme.md
Unescape Escape View File

@ -1,20 +1,11 @@
TODO: a file where to keep references
# Worlding and Software # Worlding and Software
![3D cover](cover.jpg) 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?
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 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. 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 ## Enter documentation
Could software documentation: Could software documentation:
@ -24,139 +15,51 @@ Could software documentation:
2. be an interface between different knowledges? 2. be an interface between different knowledges?
3. be a device to trigger different kinds of economy around situated software? 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) # Outline
- _Debugging_ (P5js Education Working Group, 2015)
- _(750)_ ## 0. Intro - Coding contingencies
_750_
### 2.3 Orientate software in the world ## 1. Who is reading?
_2000_
_Who is making the software?_ The first chapter focuses on code documentation as publishing surface. Who is welcome, who is addressed, and who is left out.
- Post-meritocracy manifesto (Ehmke, 2018) 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.
- "We acknowledge the value of all contributors as equal to the value of contributors who are engineers."
_How are we making it?_ __Sections:__
- Patterns of Software (Gabriel, 1996) 1. Getting started
- Situated Software (Shirky, 2004) 2. Code companion
- Aesthetic Programming (Geoff & Soon, 2022) 3. Welcoming writing
- _Wheatering software winter_ (100R, 2022) 4. Natural readers
- Ways of Being (Bridle, 2022)
- _(750)_ ## 2. Who is writing?
_2000_
## 3. Situated software requires situated documentation (3000) The second part explores documentation as a crossroads, where different knowledges meet in the making of software.
### 3.1 Situated software lifecycle. Inner public, outer public. 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.
- Inner public is the target audience of a situated software. The community where it has been developed. _Private public._ __Sections:__
- 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)_ 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.
### 3.2 A recipe in the making. A section about who is writing documentation, and how. Different strategies to approach it, from different knowledges. `wip`
Documenting situated practices as an ongoing process. ## 3. Hello Worlding
_2000_
- Techno-solutionism reversed: are we the solution to our tools' problems? The third section is focused on worlding, and the relation between code, documentation practices and political aesthetic.
- A praise for partial solutions
- _(1000)_ 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)
### 3.3 Code as common. __Sections:__
Documentation as loose interface between different needs. 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.
- Situated documentation is tailored on specific needs, and produced from specific perspectives. A second part of case studies. The soupboat. Avantwhatever.net. Queer Motto API. The Screenless Office. The uxn ecosystem. `list wip`
- How can it resonate with different ones?
- _(1000)_ ## 4. Outro
_750_

Write Preview
Loading…
Cancel
Save