There are words around code: they create entry points and help understand software. They offer ways to reason about programming, they highlight certain features and hide undesired flaws. They describe the surroundings of an application: how does it interact with neighbouring systems and how does it address involved developers. These words make worlds around code. Worlds with embedded values, active actors and politics of participation. This pathway focuses on the usage of words and technical terminology in README files, on the assumption they imply, on the ways they are choosen. These README play by avoiding or insisting on specific terms, inflating tech jargon and opening backdoors for the participation of different sensibilities in the making of code.
This collection begins with strategies explored during the past two years of within the context and infrastructure of the Soupboat, a small self-hosted server home to various piece of software and experiments.
Hello Worlding - Programming Language
It's not just about the content and approach to technicalities, but also the very language in which they are formulated and presented.
Historically code documentation has been aimed at a very specific audience. The places where software used to be developed—universities, civilian and military research labs and IT companies—were mostly populated by white dudes. This really particular monoculture probably comes as a result of several overlapping factors: the prohibitive costs of higher education, the concentration of foundings in really specific parts of the Western world, a patriarchal society that didn't foster women in technical sectors, and a racist and segregative model that systematically forced minorities and people of color into subaltern and menial tasks.
Ellen Ullman is a programmer and writer, one of the few women to work as a developer in Silicon Valley in the 80s and 90s. The combination of a liberal arts background, being a self-taught programmer, and above all being a woman, made her the archetypal outsider in the IT industry. At the same time, this very position granted her a unique ethnographic perspective, able to look critically at this environment from both the inside and from the outside.
In her books, she recounts how the presence of female figures in the IT sector was uneven: when she visited tech conventions, women were only to be found among computer trainers and technical writing conferences, some of them in the application development field, "high-level, low status, relatively-low payments" . Closer to the machine: the desert. In the low valley of programming not a female person in sight, for these more technical conventions are gathering of young men. (1997, 2016)
Many episodes in her writings describe interactions with colleagues in which she is directly attacked for being a woman who dares to enter the technical zone of engineering. Or a client harassing her while she was working to fix his database. Or the segregation of cheap latina workers hired to do mechanical data entry in the area outside the mainframe room, where all the other guys were gathered.
This condition is also reflected in the pages of code documentation. Technical manuals and software specifications have been writtem for—and from the point of view of—this very specific public, populated mainly by male engineers.
Mara Karayanni researches technical documentation from a feminist perspective. The project Read The Feminist Manual, published by Psaroskala Zine, presents an investigation of gendered language in software manuals. A case study is about the gettext localisation tool from the GNU community. The program provides a system to internationalise other code, allowing developers to translate prompts and contents in different languages other than English. It's an application that already implies a collaboration between different kinds of knowledge (developers, translators) in the making of software. Nevertheless, the manual begins with the sentence:
"In this manual, we use he when speaking of the programmer or maintainer, she when speaking of the translator, and they when speaking of the installers or end users of the translated program."
This gendered language comes with an embedded division of roles.
Open-source software development happens through code contributions within communities, and indeed someone submitted a patch to change the pronouns in the documentation, proposing a neutral approach to undoing the stereotypes and broadening the people represented by the documentation. But the patch was rejected, and the pronouns remain. Eventually, a disclaimer was added: that the gendered language does not mean that certain roles are best suited to men, and that the wording is simply a way of writing clearer instructions.
Karaianni reports further discussion on the GNU mailing list, where the proposal was rejected in favour of grammatically correct English, and because there was no perceived need for fair representation in a technical object. As argued in Read The Feminist Manual, the resistance against gender neutral language in technical writing is just a pretext for refusing to waiver the priviledge of the male programmer.
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 with the very language and attitudes used in writing documentation. From this perspective, documentation becomes an important space for building community around software. Who are we writing code documentation for? Who will read it? Who are we keeping out and who are we letting in? Who is represented and who feels invited and welcomed?
From Hello Worlding - Entry Points/Programming Language
Padliography - Deployment? Production?
Trying to reclaim the usage of terms such as "deployment" and "production", in order to problematize their normalized use and offer a redemption-arc by using them in a different way.
There are so many technical terms I'm not confortable just using, so I need to negotiate a glossary.
Sometimes to find alternatives: like what happened with the naming of default branch in platforms such as GitHub, that switched from master to main in order to stop using terms related to slavery.
Sometimes to retreace genealogies, that is: to offer other contexts for a word to refer to. A redemption arc for cursed words. No clue how to do it though, a way could be to use them critically, stumbling upon them, connnecting with different images. So here some attempts.
Deployment in software and web application means to push changes from a development environment to a production one. To move and install the code from your computer to a server, for example.
When writing a piece of documentation together with my friend Chae, she reacted puzzled to my generic use of this very specific word? I reacted puzzled to this puzzlessness, and went searching for the real-world meaning of a term imported and naturalized in the technical jargon.
Deployment is a military term, that refers to moving troops and army around on the battlefield. The spatiality of this gesture, going from home to the warzone, or from a target to another, suggests a form of detachment from its consequences, rendering them far away. Do we feel less responsible for what's happening so far? Perhaps the contrary. When something goes wrong on a distant server, what we feel is the helplessness of something being out of reach.
It's not surprising that technologies developed within army still talk a soldiers' language. But being so un-surprising, words and the worlds they carry along sneak into our worldviews, becoming normal, natural, invisible. Becoming just the way the world is, justifying and reinforcing the separation between user and developer, server and served, etc.
Looking at etymology, deploy feels close to display. They share roots and gestures of making something visible and public, not to seclude it far away, but to make it accessible.
Let's see.
From the readme of pad-bis
Queer Motto API - Refuse Tokenism
Application Programming Interface (API) is a computing interface that enables interactions, or the exchange of data, between software programs and applications. API exposes data to be shared, automated, circulated and redistributed in wider computational culture, and therefore it acts as an interface by representing and defining the possible functions of the exposed components. API's are commonly used in software industry and platforms by GAPPLE and Gam$zon - Software-as-Service (SoS) to externalise financial risk onto publics -for more on this see POTs: Protective Optimization Technologies.
Big Tech APIs operate in ways to violently arrange life, rendering it portable, modular and as a resource to profit from. It is not (just) the stack that we need to launch relentless attacks against but the web of API's that stretch from the streets to the sheets. Gam$zon are using their compute power (and they really have a lot compute power, algorithmic power and other resources such as data centres, recommendation engines, dedicated global cable infrastructure, access to private data, thousands of (often exploited) data processing workers at the disposal) to become the one who make all decisions for life from how they store and process data about our streets to who decides and recommends who we love and desire - "we refuse this and we are an army of lovers because it is we who know what love is. Desire and lust, too. We invented them"(Act up 1990).
With the Queer Motto API we make the source code available, undisciplined and vulnerable to (re)externalise risks and offer to share our compute with you. Queer Motto API creates a space for others to build apps and generate mottos on their website by following our API specification. We invite users & requesters to think about how we can imagine refusal strategies against Big Tech, normative API life and cloud computing--to address the huge inequalities presented by who has the right and resources to compute and to tactically multiply the possibilities for living.
The Queer Motto API consists of generative allied mottos and refusal messages to infuse your day, reorganise your collective life and fight injustices in the present. The generative allied mottos are based on manifestos and zines for queer and intersectional life which create a source text for machine learning and generative processes. To generate the Queer Mottos, the project uses recurrent neural networks to train and process sequences of collective voices read from the source text, as well as a diastic algorithm to establish a structure. Undisciplined and vulnerable, the program also implements computational logics to perform refusal at the infrastructural level, generating refusal messages that are found in our collection of queer and intersectional source text.
From the readme of Queer Motto API
Hello Worlding - Welcoming Writing
Writing documentation is demanding. It's more delicate than programming, and requires a whole set of skills not usually treasured by the dev community. A kind of emotional intelligence and sensitivity that is far to be found in the competitive and pragmatic wastelands of the IT industry. Nobody here wants to write documentation, or pay anyone to do it. As a result, in a world where software thrives, documentation still seems to be a scarce resource.
It's ok, someone could argue, every question that can be asked on Stack Overflow, will eventually be asked in Stack Overflow (versioning Atwood, 2007). The popular Q&A website for developers is just an example of digital knowledge as a shared effort, together with the endless mailing lists, forums, discord servers and dedicated sources for whatever topic. It's astonishing how online communities can tackle any problem in no time.
But it's not rare for these places to feel unwelcoming, or even hostile. In 2018, Stack Overflow publicly admitted that it had a problem with its user base. The space felt unfriendly for outsiders, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018).
There have been discussions about tone on the platform for years. At the question "Should 'Hi', 'thanks', taglines, and salutations be removed from posts?", one of Stack's founders responded with a RegEx to automagically find & remove what some of the experienced users perceived as noise. This regular expression, a way of targeting specific text patterns in programming, then began to be silently applied to every request sent to the website, trimming out etiquette and leaving only technicalities.
Far from being just an isolated problem, this crudity is deeply embedded in the IT discourse, soaking through technical writings as well. The denigrating expressions of superiority in matters concerning programming which Marino calls encoded chauvinism (2020) constitute the main ingredient in the brew of toxic geek masculinity. Real programmers don't use that code editor. Real programmers don't use that programming language. Real programmers don't care about others feelings. Etc.
Ellen Ullman's accounts of the emotional dumbness of her real programmer colleagues offer a glimpse of a problematic behavior, that was first intercepted and then capitalised on by the IT industry. "In meetings, they behave like children. They tell each other to shut up. They call each other idiots. They throw balled-up paper. One day, a team member screams at his Korean colleague, 'Speak English!' (A moment of silence follow this outburst, at least.)" (Ullman, 2017)
Programming means dealing with picky stubborn machines that won't overlook a single typo. It requires a high tolerance for failure. It is frustrating. But to project that frustration onto other users, as in the typical response to a request for help of Read The Fucking Manual, is a form of negative solidarity: others should suffer as I have when trying to understand how code works.
Mark Fisher used the image of negative solidarity in the context of labor under capitalism, where workers are forced into precarity and isolation. Here as in a downward auction, people are driven to bring each others down, to wish to others their same struggles. (2013) I'm using it with a focus on the emotional component: not only the lack of empathy and solidarity, but also the reproduction and legitimisation of toxic behaviours in coding communities. When all the energies are invested in optimisation and debugging, in considering and solving only techical problems, and no space is left for introspection, programmers start to behave like machines. This lack of empathy is a barrier to the participation of others in the making of software.
Here are 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 an online port of Processing, itself being a project to promote both software literacy in the visual arts, and visual literacy in software development.
The documentation work around p5.js provides entry points into the world of programming, being careful not to take too much for granted. For example, the amount of care and effort in their tutorial about debugging, results in a welcoming article with multiple levels of accessibility. Here the drawings help to visualise complex concepts, the tutorial format is beginner-friendly, and the narrative makes for an interesting reading even for those already familiar with debugging.
One of the most frightening aspects of programming is being confronted with stack trace errors: when things don't work as expected and red error messages appear. These scarlet letters delivered by the code are useful for developers to identify where in the program the error occurred, but they are often dense with technical jargon and difficult to decipher: a 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 become less alien and scary, less like a wall and more like a starting point for fixing the error.
Another reflection on entry points and gatekeeping comes from the English artist and writer James Bridle. Their practice explores the cultural and environmental impacts of digital computation, walking and jamming the fine line between what is shown and what is kept hidden in the technological landscape we live in.
When you open the browser inspector on the Facebook website, you are confronted with a wall. A message printed in the console prevents users from accessing the page's hidden structure. The platform adopted this approach to prevent scams and self-XSS attacks on its users, who could have been tricked by malevolent people into running malicious code in their own browsers. However, instead of encouraging its user base to understand, explore and ultimately feel safer against these cyber-attacks, the company opted for a full stop, marking a clear line between users and developers.
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 into 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 that allows users to see the underlying code of the website they are visiting. From here it provides some guidance for newcomers to access, inspect and modify the source code of web pages. A process that opens doors and lets people in, giving them more agency by demistifying technology.
Whether in a large project or a small gesture, attention to language can be transformative. In code documentation it can help deconstruct the false dichotomy between programmer and user, or pro and newbie. It can create spaces that feel safer, where people are invited to participate, express themselves and contribute to the community. It can help undo the impostor syndrome that affects many programmers, and that feeds on some hidden and inaccessible fundational knowledge that is nowhere to be found in code documentation. It can help shed some light on the massive amount of work that goes into the making of software: recognising all contributions, not just those of engineers.
From Hello Worlding - Entry Points/Programming Language
Readme from flask-example
A piece of documentation made together with intimate publisher Chaeyoung Kim, with a particular attention to write in a welcoming way, to encourage green developers to familiarize with the development workflow. To address this particular public every technical detail (.env files, .gitignore, the usage of terminal), is inflated and explained pointing at useful resources.
SET UP (Actors: you and your local computer)
Open the terminal! Don't be afraid! If I(we) can do it, you can do it too.
Clone this repository (aka 'repo')
git clone https://git.xpub.nl/manetta/flask-example.git
then navigate to the folder. Find more information on how to navigate in the terminal: shell_cheat_sheet (https://pzwiki.wdka.nl/mediadesign/Shell_Cheat_Sheet)
cd flask-example
Create a virtual environment. This is a contained workspace where you can install packages and libraries. It is useful in order to keep track of external dependencies, avoid version conflicts, and it provides handy tools to share your workplace with others or install it somewhere else later on. Read more in the wiki ⛄︎!
python3 -m venv venv
This will create a virtual environment in a folder called venv.
Note that the first venv is the command, the second venv is the name of the folder.
Once the virtual environmnent folder has been created, you need to activate it. There are different ways to do it, depending on your operating system.
On Mac and Linux
source venv/bin/activate
On Windows
venv\Scripts\activate
If everything went ok you should notice that the virtual environment (venv) is now active in your terminal.
Find more information info here: Python Virtual Environments: A Primer
Now you can install the requirements. For this small example the only required packages to install is Flask.
pip install flask
Now you are ready to go!
From flask-example