`Flow #1`
Documentation broadens participation in the making of software: lowering barriers and offering entry points for people to understand and attune with code.
`Flow #2`
Documentation as a backdoor where to inject political aesthetic into software: to host principles in close contact with algorithms, letting them entangle and shape each other.
This research explores these two currents, with the thesis that code documentation is an ideal publishing surface to create worlds around software, and to orientate software in the world.
The first flow seems nothing new, just the nature of every kind of technical documentation. To encode and filter knowledge, and ultimately to share it with others. Here documentation stands at a vantage point: by reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. Although, in order to make use of this sweet spot several issues need to be raised: documentation often doesn't feel welcoming for programmers others than dudes. Code documentation is still very gendered, and makes a lot of assumptions about who's reading. Addressing the problems of who is reading means also to aknowledge the counterpart of who is writing. Reading code documentation highlights that the making software does not stop with coding: that there is a massive labor of care besides engineering headaches, and that is valuable as much as technical contribuitions.
The second one is more labile and subtle: it deals with softer things than software. With political choices that inform technical details, with code close to codes of conduct, with power dynamics and forms of exclusion in the making of software. It is slippery matter, practiced with a range of different approaches, such as reclaiming spaces, re-enchanting tools and reassuring others.
### Coding contingencies
```todo
```todo
- elaborate on references
- how to quote propperly an introduction from a book series? (software studies)
- how to quote propperly an introduction from a book series? (software studies)
- elaborate on citations
```
```
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.
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.
The IT class in a public school. The job requirements for working in a tech company. An Arduino board received as gift for birthday. A colleague passionate about experimental music that drags you to a live coding concert.
The IT class in a public school. The job requirements for working in a tech company. An Arduino board received as gift for birthday. A colleague passionate about experimental music that drags you to a live coding concert.
@ -22,6 +41,16 @@ The main focus of this research is to explore software documentation as a surfac
A way to situate programming in specific contexts.
A way to situate programming in specific contexts.
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/).
Another term to democratize (_dismantle?_) 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 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.
```note
These three paragraphs are to readjust a bit after the new intro addition
```
The first chapter focuses on documentation as publishing surface. Who is reading, who is addressed, and who is left out.
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. By reaching not just 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.
@ -30,9 +59,3 @@ Documentation is a space that interfaces between the code, the user, the develop
The third section is focused on worlding, and the relation between code, documentation practices and political aesthetic.
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)
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)
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/).
Lastly, another term to democratize (_dismantle?_) 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 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.
@ -4,11 +4,11 @@ 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)
_References for technology and worlding_: Trans\*feminist Servers, Zach Blas, Tiger Ding Sun, James Bridle, Soon and Cox, Richard Gabriel.
_References for technology and worlding_: Trans\*feminist Servers, Zach Blas, Tiger Ding Sun, James Bridle, Soon and Cox, Richard Gabriel.
_Case studies_: The soupboat. Avantwhatever.net. Queer Motto API. The Screenless Office. The uxn ecosystem. `list wip`
_Case studies_: The soupboat. Avantwhatever.net. Queer Motto API. The Screenless Office. The uxn ecosystem. `list wip`
### Documentation as backdoor
### Documentation as backdoor
```note
```note
@ -18,9 +18,9 @@ _Case studies_: The soupboat. Avantwhatever.net. Queer Motto API. The Screenless
- weaving technical and political together
- weaving technical and political together
```
```
Programming, as most of all the other technical worlds out there, strive to be purely technical. Immaculate from the sin of politics. It happens to read comments from users that demand to keep politics out from code repository. Building on the western tradition of separate fields of study, coding wants just to be coding. Everything is about performance and speed, new updates and features. A space where all problems are mechanical and can be solved.
If we follow mainstream narratives, programming strives to be purely technical. Immaculate from the sin of politics. It's not rare to read comments online from users that demand to keep politics out from code repositories. Faithful to the western tradition of separate fields of study, coding wants just to be coding. All about performance and speed, new updates and features. A space where all problems are mechanical and can be solved.
But it wouldn't be fair to think that programmers simply don't care. Sometimes it's just a matter of being exposed to certain ways of thinking. Before the bachelor at the Accademy of Fine Arts for example, I've never been exposed to the writings of Donna Haraway, and I had no idea that concepts from feminism could have been so relevant for me.
But it wouldn't be fair to think that programmers simply don't care. Sometimes it's just a matter of being exposed to certain ways of thinking. Before the bachelor at the Accademy of Fine Arts for example, I've never been exposed to the writings of Donna Haraway, and I had no idea that concepts from feminism could have been so relevant also for me.
```note
```note
if you cite Haraway better explain why it's important for you etc
if you cite Haraway better explain why it's important for you etc
@ -30,13 +30,9 @@ Ellen Ullman is a programmer and writer, one of the few women working as develop
Here code documentation could work as a backdoor: hacking its way to people that have never been exposed to certain topics. A way to offer an entry points to other worlds, and ground political choices into technical details.
Here code documentation could work as a backdoor: hacking its way to people that have never been exposed to certain topics. A way to offer an entry points to other worlds, and ground political choices into technical details.
```placeholder
_Aesthetic Programming - A Handbook of Software Studies_, by Winnie Soon and Geoff Cox is an example on how to weave together these different discourses. The book explains the basic concepts of programming: it starts from variables and loops, to arrive at more complex topics such as machine learning or speech recognition. The technical curriculum offered is in line with other similar resources that target non-engineers. What's different here is a commitment to critically enquiry themes such as colonialism, racism, gender and sexuality, capitalism and class, and how are they embedded in code.
image: a diagram with two directions : documentation as entry points for developer - documentation as way to inject worlds in software
```
_Aesthetic Programming - A Handbook of Software Studies_, by Winnie Soon and Geoff Cox is an example on how to weave together these different discourses. The book explains the basic concepts of programming: it starts from variables and loops, arriving to more complex topics such as machine learning or speech recognition. The technical curriculum offered is in line with other similar resources that target non-engineers. What's different here is a commitment to critically enquiry themes such as colonialism, racism, gender and sexuality, capitalism and class, and how are they embedded in code.
Soon and Cox prepared these lessons for students enrolled in a design institution, and curated the pubblication targetting a public somehow familiar with the discourses around software studies. Thanks to the vantage point of writing documentation for beginners, they could be super explicit and go all out with generous amount of references.
Soon and Cox prepared these lessons for students enrolled in a design institution, and curated the pubblication addressing a public somehow familiar with the discourses around software studies. Thanks to the vantage point of writing documentation for beginners, they could be super explicit and go all out with generous amount of references.
Note that this work of care is not always possible. Sometimes the context doesn't feel safe to be so exposed, or there are no energies, or time, or means available. Sometimes it is necessary to act in a more nuanced way. To leave breadcrumbs and sow seeds. Or to raise voice and be firm. Different ways for different moments.
Note that this work of care is not always possible. Sometimes the context doesn't feel safe to be so exposed, or there are no energies, or time, or means available. Sometimes it is necessary to act in a more nuanced way. To leave breadcrumbs and sow seeds. Or to raise voice and be firm. Different ways for different moments.
@ -120,16 +116,19 @@ see different implementation of uxn
The same with DuskOS, a small operative system that reactivate the ancient programming language Forth within ecological perspectives
The same with DuskOS, a small operative system that reactivate the ancient programming language Forth within ecological perspectives
```
```
### Reassure
### Reassure
```placeholder
documentation to keep going, to reassure, to bond
documentation to keep going, to reassure, to bond
```
### Education and initiation
```note
```note
not sure where to put this, is not part of the reassure. More connected to the nuanced way of the backdoors section
not sure where to put this yet
it is to elaborate why this idea of backdoors vs for example just rebranding
```
```
We tend to put ourselves in difficult situations. By aknowledging complex problems, we aknowledge also the impossibility for simple solutions.
We tend to put ourselves in difficult situations. By aknowledging complex problems, we aknowledge also the impossibility for simple solutions.
@ -142,4 +141,4 @@ Three sources that could be explored here relate to an alternative to the model
- the plot of her undoing - saidiya hartman - the undoing of the plot
- the plot of her undoing - saidiya hartman - the undoing of the plot
- federico campagna - technics and magic - _taqiyya_, _kitman_ and secret - education vs initiation
- federico campagna - technics and magic - _taqiyya_, _kitman_ and secret - education vs initiation
- a way of saying from bergamo dialect about fire and embers
- a way of saying from bergamo dialect about cinders and embers
- [Franklin Ace 1000 user manual](https://www.ironicsans.com/ace1000.pdf)
- [Franklin Ace 1000 user manual](https://www.ironicsans.com/ace1000.pdf)
- [knowing machines - critical field guide](https://knowingmachines.org/critical-field-guide)
- [knowing machines - critical field guide](https://knowingmachines.org/critical-field-guide)
- [gendered language feature or bug in software documentation](https://modelviewculture.com/pieces/gendered-language-feature-or-bug-in-software-documentation)
