Code documentation is an interface between the code, the user, the developer, and the world. Living close to the source code, but at the same time being less rigid and more expressive, documentation seems to be an ideal surface where to open entry points and backdoors in the practice of software development. A crossroads where different knowledges meet in the making of software: beginners moving their first steps into coding, as well as experienced programmers looking for reference on a particular function. A space where to acknowledge the massive labor of care involved in coding culture besides technicalities, otherwise often marginalized. A place where to welcome different voices: not just engineers, not just experts, not just dudes. A way to broaden participation.
How to create entry points for more people to participate to programming practices?
How to facilitate more diverse communities around coding?
How to acknowledge the value of different perspectives in the making of software?
Code documentation seems to be a crossroads where different knowledges meet in the making of software. 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 where to acknowledge the massive labor of care besides technicalities, often marginalized by coding culture.
```note
is this first paragraph too declarative to be a research question?
```
### Two flows
There are two flows around code documentation:
There are two flows around code documentation:
@ -22,20 +19,17 @@ Documentation as a backdoor where to inject political aesthetic into software: t
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.
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 but 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 acknowledge 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 contributions.
The first flow seems nothing new but 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. In order to take advantage of this sweet spot however, several issues need to be raised: documentation often doesn't feel welcoming for programmers others than dudes. Code documentation's language is still very gendered, and makes a lot of assumptions about who's reading it.
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, enchanting tools and reassuring others. 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 contributions.
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, enchanting tools and reassuring others.
```placeholder
```placeholder
And these different techniques will be addressed in the second part of the thesis.
And these different aspect will be addressed in the second part of the thesis.
```
```
### Coding contingencies
### Coding contingencies
```todo
- elaborate on references
```
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.
@ -56,19 +50,15 @@ The concepts of worlding, political aesthetic, and critical thinking can be appl
```placeholder
```placeholder
Some examples of documentation, different types and intensities
Some examples of documentation, different types and intensities
```
```
Another term to contextualize (and dismantle?) here is _developer_.
Another term to contextualize (and 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 Ullman writes that programming is a disease, but the situation is even worse: code is contagious material, touch it once and you are a 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 Ullman 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
This thesis explores code documentation more as an interface then as a publishing surface. A permeable passage from us to code, and from code to us.
Next three paragraphs are to readjust a bit after the new structure: chapters 1 and 2 are merged and are a first part about entry points.
```
This thesis explores code documentation as a publishing surface.
The first part focuses on who is reading, who is addressed, and who is left out. Code 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.
The first part focuses on who is reading, who is addressed, and who is left out. Code 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. In order to create accessible entry points and speak to different people however, it's necessary to question the usage of language, to criticize the amount of energies required for writing, and to address problems of inclusivity within tech communities.
The second 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)
The second 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) A backdoor to inject context around technical and non-technical choices.
code documentation as a publishing surface to create entry points?
yes because
yes because
it's often first thing one reads when approaching software - see getting started
1.1 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
1.2 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
1.3 it should be less hostile - see welcoming writing
it should stop assuming reader - see natural readers
1.4 it should stop assuming reader - see natural readers
```
```
### Getting started
### 1.1 Getting started
```note
```note
("Getting startled" could also make for a nice title)
("Getting startled" could also make for a nice title)
```
```
@ -27,7 +27,7 @@ The introduction to a program situates it also within a larger ecosystem: how to
The initial imprinting of documentation is a vantage point to orientate code in the world.
The initial imprinting of documentation is a vantage point to orientate code in the world.
### A code companion
### 1.2 A code companion
The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the specifics of a particular programming language or platform. Sometimes for the web, sometimes for a hardware component, sometimes for another operative system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just knowing by heart a programming language, but rather having to deal with a lot of different recipes for different occasions, and know how to adapt.
The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the specifics of a particular programming language or platform. Sometimes for the web, sometimes for a hardware component, sometimes for another operative system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just knowing by heart a programming language, but rather having to deal with a lot of different recipes for different occasions, and know how to adapt.
@ -44,12 +44,12 @@ A text that fails to address who's reading can result inaccessible and frustrati
```note
```note
think about:
think about:
- move next paragraph in worlding chapter?
- move next paragraph in worlding chapter?
- unpack political aesthetic
- unpack political aesthetic or use a different term, not sure if there is the headspace to go into RancR atm
```
```
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)
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
### 1.3 Welcoming writing
The potential of documentation to orientate software in the world clashes against some big elephants in the room, and tech culture should stop keep them in captivity. Sure, it would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available.
The potential of documentation to orientate software in the world clashes against some big elephants in the room, and tech culture should stop keep them in captivity. Sure, it would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available.
@ -101,57 +101,32 @@ Message in console printed by Facebook to stop users - source: booktwo.org
Message in console printed by Bridle to welcome users - source: booktwo.org
Message in console printed by Bridle to welcome users - source: booktwo.org
### "Natural" reader
### 1.4 "Natural" reader
```note
- assuming a certain kind of reader - expert - dude
- references:
- programming for the millions (ullman, 2016)
- read the feminist manual (karagianni, 2021 )
- bro culture ? ? ?
(could be the transition from previous section)
(could be the example with evvvvil help patches)
- refer to a specific cultural niche ? see ullman, even tho need to counter balance with other examples
- manuals often address just male developers
- often documentation doesn't offer entry points for beginners, or a sense of direction, this esp a problem with hypertexts
```
- who writes code documentation tends to assume a certain kind of reader, to talk a specific language, to refer to a particular context
sections
__expert reader, formerly educated reader__
- takes for granted the technical level of the reader
A whole range of different people read code documentation.
takes for granted a specific lexicon,
relates with external sources without referring to them
__male! developer often addressed as he/him__
- within a particular cultural niche! western
- dude
- Who writes code documentation tends to assume a certain kind of reader:
- expert, formerly educated reader
- takes for granted the technical level of reader
- takes for granted a specific lexicon,
- refer to a broader context or previous, not explicit references
- see programming for the millions (ullman, 2016)
- problems of language
- gendered writing and gendered roles
- developer often addressed as he/him
- dude culture and toxic masculinity
- example machism, vvvv twitter-api help patches
- example encoded chauvinism
- a whole range of different people read code documentation!
- again diataxis: different format for different levels
- offer guidance between milions references
- goat meme
```note
A couple of brainstorming paragraphs feel free to skip sorry for the inconvenience
```
Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers.
Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers.
@ -163,11 +138,13 @@ Learn to code is like learning another language: not just a new bag of words and
Coding means to express ideas with the reduced vocabulary of a programming language.
Coding means to express ideas with the reduced vocabulary of a programming language.
when writing need to share a way to think to software
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.
### 1.5 Documentation as gardening
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.
- Code documentation require as much maintainance as code itself
- Updates, corrections, additions, translations
- Massive amount of energy required
- Gendered labour
- Documentation as subaltern work (in open source projects)
- [They dont make computer manual like this anymore](https://www.ironicsans.com/2010/02/they_dont_make_computer_manual.html#comment-403451)
- [They dont make computer manual like this anymore](https://www.ironicsans.com/2010/02/they_dont_make_computer_manual.html#comment-403451)
- [Franklin Ace 100 user manual](https://www.ironicsans.com/ace100.pdf)
- [Franklin Ace 100 user manual](https://www.ironicsans.com/ace100.pdf) (see [birds press 05](https://git.xpub.nl/kamo/birds-press/src/branch/main/covers/05_Franklin-ACE-100-Operators-reference-manual.jpg))
- [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)
