6.5 KiB
0. Intro
explicit research question
There are two flows around code documentation:
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.
And these different techniques will be addressed in the second part of the thesis.
Coding contingencies
- 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.
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.
Some examples of documentation, different types and intensieties
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 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.
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. 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 is 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.
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)