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.
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.
```note
is this first paragraph too declarative to be a research question?
```
There are two flows around code documentation:
There are two flows around code documentation:
@ -21,39 +16,21 @@ This research explores these two currents, with the thesis that code documentati
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 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 inclusion and exclusion in the making of software. It is slippery matter, practiced with a range of different approaches, from artistic practices to digital activism. 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 and create most of the context around code.
### 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.
These contingencies are situated in specific contexts.
Programming then is not just sharing code, but sharing context. A significant statement about our relationship to the world, and how we organize our understanding of it (Ullman, 2017). A perspective to look at reality, before attempting to get some grip onto it with a script. A way to deal with both the software and hardware circumstances of code (Marino, 2020), but also engaging with the sociality and communities around it.
It's an approach that helps us to think about software as a cultural object. Something "deeply woven into contemporary life –economically, culturally, creatively, politically– in manners both obvious and nearly invisible." ( Fuller, Manovich and Wardrip-Fruin, 2009), and not just as technical tool existing in a vacuum.
An object that, in turn, can be used to probe its surroundings. Who is developing? Who is going to 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 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.
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 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.
```placeholder
Next is to unwrap what does code documentation mean. In these writings the term refers to a set of different practices: from technical manuals to coding workshops, from comments weaved with lines of code to video tutorial. Code documentation is a technical object itself, one with very blurry boundaries. A lack of structure that can be used in turn to mold our wishes and values into it. We shall look at these practices with multiple lenses, in order to gather insights from various contexts.
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.
This thesis explores code documentation as an interface. A permeable passage from us to code, and from code to us.
This thesis explores code documentation as an interface. A permeable passage from context to code, and from code to context.
```note
ùpdate once again the next paragraphs
```
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 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.
@ -21,6 +21,23 @@ Here documentation is seen as a surface that could host principles in close cont
- what can be changed?
- what can be changed?
```
```
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.
These contingencies are situated in specific contexts.
Programming then is not just sharing code, but sharing context. A significant statement about our relationship to the world, and how we organize our understanding of it (Ullman, 2017). A perspective to look at reality, before attempting to get some grip onto it with a script. A way to deal with both the software and hardware circumstances of code (Marino, 2020), but also engaging with the sociality and communities around it.
It's an approach that helps us to think about software as a cultural object. Something "deeply woven into contemporary life –economically, culturally, creatively, politically– in manners both obvious and nearly invisible." (Fuller, Manovich and Wardrip-Fruin, 2009), and not just as technical tool existing in a vacuum.
An object that, in turn, can be used to probe its surroundings. Who is developing? Who is going to 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 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.
```placeholder
```placeholder
- to expose people usually out of reach to different contexts
- to expose people usually out of reach to different contexts
