6.0 KiB
0. Intro
!!! note "structure for intro" code documentation entry points and backdoor relation between these two: nature of code documentation is to create entry points but actually there are a lot of issues around these entry points because of approaches, language, formats, economies so it's worthed to search for other ways in enter backdoors ways to infiltrate programming practices inject different values and contexts to open even more entry points
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.
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 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 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.
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.
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.
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.
This thesis explores code documentation as an interface. A permeable passage from context to code, and from code to context.
The first part focuses on languages, formats and approaches of code documentation, to broaden participation in the making of software by questioning 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) A backdoor to inject context around technical and non-technical choices.