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.
!!! note "code documentation as a publishing surface to create entry points?"
The nature of code documentation is to create entry points for people to participate in programming practices. This "nature", however, comes not without issues: due to assumptions on who is reading the documents, the approaches, language, and tone used to illustrate the contents, and the amount of time and energies required for maintenance. These problems are addressed in the first part of this section.
yes but
it should stop assuming reader - see natural readers
it should be less hostile - see welcoming writing
yes because
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
!!! note "for structure: entry points"
Researching languages, formats and approaches of code documentation to broaden participation in the making of software
1. Natural readers
2. Programming Language
2. Welcoming writing
3. Docs as gardening
4. Getting startled
5. Code companion
Even doing a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface that stretches through time and space. Time because it meets programmers in different moments of their life: when they are moving their first steps and are just beginners, as well as when they are more navigated and need some specific references. Space because it comes with many different possible formats, and can shapeshift to serve diverse occasions. The question then is: can we make use of these backdoors to infiltrate programming practice and open more entry points from the inside?
### "Natural" reader
@ -27,7 +12,6 @@ When it comes to contents, the reader is often thought similar to who's writing:
Whenever too much technical proficiency is required to even read documentation itself, knowledge results inaccesible and confined in the ivory tower. An important detail to notice here is that this is an antipattern that reinforces the segmentation between who is allowed in and who is not: only previously educated ones can access, while others are kept out. Not filtering information becomes a filter to who can engage with it. Contents need to be curated, that does not mean over-simplified or generalized, but rather made legible.
@ -48,9 +32,9 @@ Like in _NAND to Tetris_ things are built gradually. Here however the process is
The entry points here are multiple as the spokes in a bicycle wheel. They come from different directions and don't frame the code as a prescriptive and rigid system, but rather as a crafted balance between different forces and needs in play. This kind of technical objects feel less monolithic and more approachable.
A lesson can be learned: sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about everything at the same time. Programming means to balance between these different aspects depending on the situation. Keeping it in mind when writing code documentation gives to the writer space to adjust tone, intensity and approach based on who is going to read these docs.
A lesson can be learned: sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about everything at once. Programming means to balance between these different aspects depending on the situation. Keeping it in mind when writing code documentation gives to the writer space to adjust tone, intensity and approach based on who is going to read these docs.
### Programming languages
### Programming language
It's not only a matter of contents and approach to technicalities, but also the very language with which they are formulated and exposed.
@ -81,29 +65,7 @@ Karaianni reports further discussions in the GNU mailing list, where the proposi
Toxic geek masculinity reinforces stereotypes such as gendered roles in programming, and refuses to acknowledge the participation of diverse identities in the making of software, starting from the very language and attitudes used when writing documentation. Seen from this perspective, documentation becomes an important space where to build community aroud software. For who are we writing code documentation? Who is going to read it? Who are we keeping out and who are we letting in? Who is represented and feel invited and welcomed?
---
more about language:
Not be just a process of rebranding. Cannot be just a matter of changing the visual identity of the documentation, or washing it green or pink or black, or to capitalize on the inclusion of minorities.
To create new narrations around software. As the artist James Bridle writes trying to untangle the complex social and environmental implications of digital computation: _"Technology is not mere tool making and tool use: it is the making of metaphors"._ (James Bridle, 2018) These metaphors, like code documentation, influence the way we think and use our tools.
- `Example:` Master-slave examples on version control software documentation. See [BitKeeper](https://github.com/bitkeeper-scm/bitkeeper/blob/master/doc/HOWTO. ask#L223)
- `Example:` The military term _deploy_ adopted by CI/CD systems such as the one on GitLab.
- `Example:` The naming of group of servers as _fleet_ on AWS documentation, a term referring to naval formation, again with military connotation.
These metaphors orient code in the world. They reinforce, highlight and validate certain practices. A fleet implies centralized control, a swarm implies direct influences between participants, a federation implies certain degrees of independence, etc.
Not only to _find & replace_ terms throughout the documentation, but to re-trace genealogies, to intercept and re-orient narrations, and offer a redemption arc to those projects that were abandoned.
### 1.2 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. -->
### Welcoming writing
Writing documentation is demanding. It's more delicate than programming, and require a whole set of skills usually not treasured by the dev community. A kind of emotional intelligence and sensitivity far to be found in the competitive and pragmatical wastelands of the IT industry. Here no one wants to write documentation, nor pay someone to do it. As a result, in a world where software thrives, documentation still seems to be a scarce resource.
@ -121,17 +83,15 @@ Ellen Ullman's accounts of the emotional dumbness of her _real programmers_ coll
Programming means to deal with picky stubborn machines that don't overlook a single typo. It requires a high tolerance for failure. It is frustrating. But to project this frustration onto other users, as in the `Read The Fucking Manual` typical response to a request for help, it's a form of negative solidarity: others should suffer as I did when trying to understand how code works.
Mark Fisher used this image in the context of labor under capitalist realism, where workers are forced in precarity and isolation. Here as in a downward auction, people are driven to bring down each others. (Fisher, 2013). I'm using it with a focus on the emotional component: not just lack of empathy and solidarity, but also reproduction and legitimisation of toxic behaviors in coding communities.
When all the energies are invested in debugging, the quest to find and solve all the problem in a program, and no space is left for introspection, programmers start behaving as machines. This lack of empathy it's a barrier for the participation of others in the making of software.
Mark Fisher used this image in the context of labor under capitalist realism, where workers are forced in precarity and isolation. Here as in a downward auction, people are driven to bring down each others. (2013) I'm using it with a focus on the emotional component: not just lack of empathy and solidarity, but also reproduction and legitimisation of toxic behaviors in coding communities. When all the energies are invested in debugging, the quest to find and solve all the problem in a program, and no space is left for introspection, programmers start behaving as machines. This lack of empathy it's a barrier for the participation of others in the making of software.
Here some examples that go in a different direction, on different scales.
p5.js is a popular Javascript library started by the artist Lauren McCarthy as online porting of Processing, itself being a project to promote both software literacy within the visual arts, and visual literacy in software development.
`p5.js` is a popular Javascript library started by the artist Lauren McCarthy as online porting of Processing, itself being a project to promote both software literacy within the visual arts, and visual literacy in software development.
The work of documentation around p5.js offers entry points to the world of programming, taking care of not taking too many things for granted. The amount of care and efforts in their tutorial about [debugging](https://p5js.org/learn/debugging.html), for example, results in a welcoming article with different levels of accessibility. Here the drawings help to visualize complex concepts, the tutorial format is beginner-friendly, and the narration makes for an interesting reading also for who is already familiar with debugging.
The work of documentation around `p5.js` offers entry points to the world of programming, taking care of not taking too many things for granted. The amount of care and efforts in their tutorial about [debugging](https://p5js.org/learn/debugging.html), for example, results in a welcoming article with different levels of accessibility. Here the drawings help to visualize complex concepts, the tutorial format is beginner-friendly, and the narration makes for an interesting reading also for who is already familiar with debugging.
One of the most frightening aspects of programming is to be confronted with stack trace errors: when things don't work as espected and red error messages show up. These scarlet letters delivered by code are useful for developers to identify where in the program the error happened, but often they are dense of technicalities and difficult to decipher. Worst case scenario for beginners. The explanations from the p5.js Education Working Group tackle on this nightmare showing not only how to read technical errors, but how to think through them with different debugging methods. From here the stack trace starts to get less alien and scary, less like a wall and more as a starting point to solve the error.
One of the most frightening aspects of programming is to be confronted with stack trace errors: when things don't work as espected and red error messages show up. These scarlet letters delivered by code are useful for developers to identify where in the program the error happened, but often they are dense of technicalities and difficult to decipher. Worst case scenario for beginners. The explanations from the `p5.js` Education Working Group tackle on this nightmare showing not only how to read technical errors, but how to think through them with different debugging methods. From here the stack trace starts to get less alien and scary, less like a wall and more as a starting point to solve the error.
Another reflection on entry points and gatekeeping comes from the english artist and writer James Bridle. Their practice explores the cultural and ecological impacts of digital computation, walking and jamming the thin line between what is showed and what is kept hidden in the technological landscape we live in.
@ -139,16 +99,13 @@ When opening the browser inspector in the Facebook website, one faces a wall. A
`welcome.js` (2016) is a small gesture in response, a tiny Javascript library published open source on GitHub under a permissive MIT license, where Bridle injects some greetings in their website (and in all the websites that include the library) to welcome users to the browser inspector. The artwork is hidden below the surface of the website, printed in the console of the browser inspector, a tool which allows users to see underlying code of the website they are visiting. From here it provides some guidance for newcommers to access, inspect and modify the source code of web pages. A process to open doors and let people in, giving them more agency by demistifying technology.
Whether in big project or small gesture, attention to language can be transformative. In code documentation it can help deconstructing the false dichotomy between programmer and user, or pro and newbie. It can create spaces that feel more safe, where people are invited to participate, express themselves and contribute to the community. It can help undoing the impostor syndrome that affects many programmer, and that feed on some hidden and inaccessible fundational knowledge nowhere to be found in code documentation. It can help to cast some light onto the massive amount of work around the making of software: recognizing all contributions, not just the ones from engineers.
### 1.3 Documentation as gardening
### Documentation as gardening
When the docs does not reflect the behavior of the project, or when there are discrepancies between the two of them, the reliability of both code and documentation is undermined. Code documentation requires as much maintainance as code itself. Code transforms and documentation should follow.
@ -168,11 +125,7 @@ Documentation is a surface where all the sociality, relations, and context aroun
A surface that in turn can be activated and used as a platform to reach all the different actors surrounding it.
!!! placeholder "like a backdoor!!"
### 1.4 Getting started
!!! note "("Getting startled" could also make for a nice title)"
### 1.4 Getting startled
Reading undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code.
@ -189,6 +142,15 @@ 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.
!!! note "elaborate on imprinting for non biologist friends"
_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.
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.
### 1.5 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.
coding contingencies means coding is always coding within context
programming as a way to share context
documentation to inject context into code to address issues
and create different entry points
politics of participation
economies of care
politics of representation
aesthetic practices and worlding
### 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.
@ -18,7 +30,6 @@ The main focus of this chapter is to explore software documentation as a surface
A way to situate programming in specific contexts.
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)
### Documentation & distribution
@ -156,15 +167,6 @@ In the Screenless Office, the bureau aesthetic, with its collective imagery of c
Our first project in XPUB was Special Issue 16: a collective exploration of natural language processing with a vernacular turn. It was published as an API, offering several functions to users to play with strings and texts.
### aesthetic programming as a bridge between software studies and creative coding
!!! note "where to put"
could this paragraph go in the part 1 ?
_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.
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.
