30 KiB
1. Entry points
!!! note "code documentation as a publishing surface to create entry points?"
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
"Natural" reader
Documentation that assumes a certain kind of reader can result inaccessible. This can happen for several different reasons, two of them apparently at the opposite spectrum of the problem: the very contents of documentation and the language with which these contents are exposed.
When it comes to contents, the reader is often thought similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cutting through the precise lingo and esoteric references offered as explanations. Eventually (and in most of the cases) who's reading happen to be someone else. This mismatch transforms entry points into barriers that filter out who can participate to coding.
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.
To cultivate legibility is but an easy task, especially when dealing with computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narrations and entwined plots and main characters at the same time. The purpose of an abstraction is to act as a symbol, as a mentally maneuverable concept, free from its technical implementation details. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up for the digital stack.
Take a course such the one presented by Noam Nisan and Shimon Schocken in From NAND to Tetris, where they slowly build a programmable computer able to run the classic game starting from simple logic gates, so basically from microchips and electronics. One layer after the other, from boolean operations with 0 and 1 to registers and CPUs, from machine language to high level programming. Here one can try to unwind the coil and start understanding programming from scratch scratch, but this approach is best suited to a university curriculum, and it's often not real effective when facing real-world problems, with real-world constraints, and real-world circumstances.
A deep understanding of technical systems is admirable and desirable of course, given the insights it can provide on the infrastructures that shapes our everyday lives. But it cannot be the only mode of access available. Deep understanding comes with its own learning curve, and it can be blocking for a lot of people. Yet, many, many guides resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, tracing back till the invention of the wheel.
A different kind of approach, more modelled on the way technology and coding meet us in real life, starts from the middle and tries to make sense of its surroundings. One could just need to make a website, for instance. And could just start doing that, following a guide or a tutorial. Soon questions would start bubbling up. Made from scratch or with a framework? And which one to choose? What about the backend? Where to host it? On which kind of server? Static or dynamic? And the Content Management System to upload new materials? And where to get the certificate for secure connection? These things surely are important, but there is no really need to know everything beforehand to put the website online. Programming is provisional: leaving TODOs in the code to come back later.
The series Programming Projects for Advanced Beginners by Robert Heaton embrace this methodology. Each projects offers some guidance through the different steps involved when coding a particular application: a login system, a simple game, a graphic filter to apply to the webcam, etc.
One nice aspect of these guides is that they don't refer to a specific programming language: they are decoupled tutorials that leave space to the reader to integrate and adapt the steps to their own coding contingencies, while at the same time helping in building a lexicon, teaching how to search for informations, reading error messages and find their way through.
Like in NAND to Tetris things are built gradually. Here however the process is iterative and circular, instead of linear. Implementations are put in place provisionally, and then reiterated and developed more: introducing new concepts not as hardcoded procedures, but as a result of emerging problems.
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.
Programming languages
It's not only a matter of contents and approach to technicalities, but also the very language with which they are formulated and exposed.
Historically code documentation has been addressed to a very specific public. The places where software was developed back in the days, universities, civilian and military research labs and IT companies, were mostly frequented 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 author, one of the few women working as developer in the Silicon Valley during the 80s and 90s. The combination of having a background in the humanities, being a self-taught programmer, and especially being a woman, made her the archetypical outsider in the IT industry. At the same time, this very position granted her a unique ethnographic perspective, capable of looking critically at this environment, both from the inside and from the outside.
In her books, she reports how the presence of female figures was unevenly distributed in the IT sector: while visiting tech conventions, women were to be found just at computer trainers and technical writing conferences, some 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 coworkers where she is directly attacked because being a woman daring to enter the (total dudes situation of) 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 room next to the mainframe's one, where all the other guys were gathered.
!!! note "" "Workers leaving the Googleplex" present this same last situation more than twenty years later, with Google pushing minorities towards subaltern unskilled work. See: http://www.andrewnormanwilson.com/WorkersGoogleplex.html
This condition is reflected also in the pages of code documentation. Technical manuals and software specifications have been addressed, and written from the point of view of, this very specific public, populated mainly by male engineers.
Mara Karayanni researches on technical documentation from a feminist perspective. The project Read The Feminist Manual, published with Psaroskala Zine, presents an investigation of gendered language in software manuals. One case studies is about the gettext localization program from the GNU community. The program provides a system to internationalize other code, to let developers translate prompts and contents in different languages other than english. It's an application that already implies a collaboration between different kinds of knowledge (developer, translator) in the making of software. Yet, the manual opens 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 separation of roles.
The GNU and the open-source software development happens with code contributions within communities, and indeed someone submitted a patch to change pronouns in the documentation, proposing a neutral approach to undo the stereotypes, and broaden the people represented by the documentation. But the contribuition was rejected, and the pronouns remains. Eventually a disclaimer was added: that the gendered language is by no mean to say that certain roles are best fit for males, and that the phrasing is just a way of writing more clear instructions.
Karaianni reports further discussions in the GNU mailing list, where the proposition is turned down in favour of grammaticaly correct english, and because no need felt for fair representation in a technical object. As argued in Read The Feminist Manual, the stubborness against gender neutral language in technical writing is but 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 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
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.
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 there was a problem concerning their userbase. The space felt unfriendly for outsiders, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018).
For years there have been discussions on the platform about tone. At the question "Should 'Hi', 'thanks', taglines, and salutations be removed from posts?", one of the founders of Stack replied with a RegEx to filter automagically what some of the experienced users perceived as noise. This regular expression, a way to target specific text patterns in programming, started then to be silently applied to every query sent to the website, trimming out etiquette and leaving just 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 that Marino calls encoded chauvinism (Marino, 2020) constitute the main ingredient in the brew of toxic geek masculinity. Real programmers don't use this code editor. Real programmers don't use this programming language. Real programmers don't care about others feelings. Etc.
Ellen Ullman's accounts of the emotional dumbness of her real programmers colleagues give an insight of a problematic behavior, first intercepted and then capitalized by the IT industry. "In meetings, they behave like children. They tell each other to shut up. The 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 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.
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.
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, 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.
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.
When opening the browser inspector in the Facebook website, one faces a wall. A message printed in the console halt users from accessing the page hidden structure. The platform adopted this approach to prevent scams and Self-XSS attacks to their users, that could have been lured into running malicious code in their own browsers by malevolent people. However, instead of encouraging their userbase to understand, explore and eventually feel more safe against these cyberattacks, the company opted for a full stop, marking a clear line between user 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 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
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.
There's a moltitude of ways in which changes in the codebase reflect on the documentation. New features ask for new sections. Breaking changes with previous versions require warnings and instructions on how to migrate towards the new one. Bugs and unexpected behaviours are to be addressed. Deprecated functions need to be trimmed out, or marked as outdated.
On top of all the technical aspects, the editorial work has to be taken into accounts. Adjustments and corrections and line-editing, clarifications of convoluted paragraphs, rephrasing of confused sentences, highlighting of important passages. Certain projects support internationalization, and the contents are translated and adapted to different languages' structures.
Documentation can be as simple as a plain text file stored nearby the code. A README.txt that invites developers to have a look before diving into the program. As projects get bigger and more articulated however, the demands for more comprehensive and structured formats arise. The printed matter of technical manuals have today transformed and spread into many different shapes. Wiki and websites generated with various tools, each with particular focus and features. All these platforms imply more work: maintainance, design and sometimes guidelines and documentation for the surface where to document itself.
Writing docs is not a once in a lifetime effort, but rather a continuous commitment. It's a process with its own pace and timing, and similar to gardening is a form of care both for code and for the community around it.
It's a process that requires a massive amount of energies and resources. Yet, it seems to be constantly understimated, undervaluated, and pushed towards the margins. Something left for when there's nothing better to do, something to delegate. Something perceived as a burden, as a killjoy, a display of weakness from real programmers that should be able to understand a program by directly reading the sourcecode.
All these effort are a good display of what advocated in the Post-Meritocracy Manifesto by Coraline Ada Ehmke and more than other six hundred signatories: the making of software is not just a matter of engineering skills, but interpersonal relations and social dynamics, where all the contributions around code are important as the one on the code itself.
Documentation is a surface where all the sociality, relations, and context around code are rendered visibile. An interface between the technical world of machines, the affective sphere of the community, the delicate and demanding economies of open source projects, and the politics of distribution, circulation and participation in the making of software.
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)"
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.
At the very first encounter with a new script, details about its source code are unknown. Programming is a play in medias res, and documentation acts as narrator. Describing how functions are stitched together, or an algorithm is implemented, it sets the stage for developers to participate. Showing the different steps of a program and how they are connected, it offers entry points for interventions.
For example Vue.js, a popular library for building web user interfaces, explains with a diagram the lifecycle of its components: at which moment data are received from a server, at what point an element is rendered on screen, and when it will disappear. What at the beginning feels like magic, gradually appears more clear. Presenting a structure means also presenting a way to reason about it. The reader gains some understanding and agency over the tools they are about to use.
The introduction to a program situates it also within a larger ecosystem: how to install it, and what dependencies it requires to work properly. As Geoff Cox and Winnie Soon elaborate on their decision of a downloadable code editor instead of a web one for their classes, code is more than just a single piece of software. It is also the relations with the configuration of one's own computer and operating system. (Cox and Soon, 2020)
The initial imprinting of documentation is a vantage point to orientate code in the world.
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.
Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering a software, and return to the references when they need a refresher on the syntax of a particular command. They continuously look at code from multiple distances: close to the source code through lines of comment—ignored by the machine, but much appreciated by fellows developers—or from printed books, along with pages of explanations and use cases.
This tentacular surface can reach a programmer in different moment of their life: from the hello world to the how to uninstall. This is possible thanks to the multitude of shapes documentation can take: video tutorials and commands cheatsheets, README files and complete guides featuring colored images. Daniele Procida proposes a systematic approach to organize this wealth of formats (Procida, 2017). His framework focuses on the needs of different kinds of readers: by leveraging between practical steps and theoretical knowledge, it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
This system organizes knowledge around code in a way that tries to meet every user possible. Tutorials offer entry points for the newcomers, while explanations unveal core mechanisms for more navigated readers. How-to guides teach how to get the work done, while references report lists of information ready to be consulted. Different documentations for different readers for the same code.
A text that fails to address who's reading can result inaccessible and frustrating. Although the Diataxis framework doesn't encompass every particular situation, its structure offers good aid to situate documentation within different perspectives. This turns out to be really helpful in the process of writing, as a way to fine tune tones and modulate the nature of shared info.