@ -61,92 +61,92 @@ Writing documentation is demanding. It's more delicate than programming, and req
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.
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 userbase. The space felt unfriendly for _outsiders_, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018).
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 userbase. 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](https://meta.stackexchange.com/a/93989) to _automagically_ filter out 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.
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](https://meta.stackexchange.com/a/93989) 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.
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.
!!! note "spell checked till here"
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. 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)
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 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.
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 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.
Mark Fisher used the image of negative solidarity in the context of labor under capitalism, where workers are forced in precarity and isolation. Here as in a downward auction, people are driven to bring down each others, to wish to others their same struggles. (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 are some examples that go in a different direction, on different scales.
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 an online port of Processing, itself being a project to promote both software literacy in 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 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](https://p5js.org/learn/debugging.html), 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.
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 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.
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 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.
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 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.
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 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.
`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.
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.
### 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.
If the docs does not reflect the behaviour of the project, or if there are discrepancies between the two of them, the reliability of both code and documentation is undermined. Code documentation requires as much maintenance as the 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.
There's a multitude of ways in which changes to the codebase affect the documentation. New features require new sections. Breaking changes with previous versions require warnings and instructions on how to migrate to the new one. Bugs and unexpected behaviour need to be addressed. Deprecated functions must 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.
In addition to the technical aspects, the editorial work needs to be taken into account. Adjustments and corrections and line-editing, clarifications of convoluted paragraphs, rephrasing of confused sentences, highlighting of important passages. Some 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.
Documentation can be as simple as a plain text file placed near the code. A `README.txt` that invites developers to take a look before diving into the program. However, as projects become larger and more articulated, the need for more comprehensive and structured formats arises. Printed technical manuals have today transformed and spreaded into many different shapes. Wikis and websites generated with various tools, each with particular focus and features.
All of these platforms imply more work: maintenance, design and sometimes even guidelines and documentation for the documentation 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.
Writing docs is not a once in a lifetime effort, but an ongoing commitment. It's a process with its own pace and timing, and much like gardening, it's a form of care both for the 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.
It's a process that requires a massive amount of energies and resources. Yet, it seems to be constantly underestimated, undervalued, and pushed to 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 by _real programmers_ who should be able to understand a program by reading its 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.
All these efforts are a good illustration of what advocated in the Post-Meritocracy Manifesto by Coraline Ada Ehmke and more than other six hundred signatories: making software is not just a matter of technical skills, but of interpersonal relations and social dynamics, where all contributions around code are important as those 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.
Documentation is a surface where all the sociality, relationships, 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.
A surface that in turn can be activated and used as a platform to reach out to all the different actors around it.
### Getting startled
### 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.
Reading undocumented code feels like being an ant walking on a big painting. You can see the brush strokes and have a sense of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides a bird's eye perspective on the bundle of functions and statements that make up software. 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 a 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.
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. By describing how functions are stitched together, or an algorithm is implemented, it sets the stage for developers to participate. By showing the different steps of a program and how they are connected, it offers entry points for intervention.
For example [Vue.js](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle-diagram), 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.
For example [Vue.js](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle-diagram), a popular library for building web user interfaces, uses a diagram to explain the lifecycle of its components: when data is received from the server, when an element is rendered on screen, and when it disappears. What at first feels like magic, gradually becomes clearer. To present a structure means also to offer a way of reasoning about it. The reader gains a certain understanding and agency over the tools they are about to use.
Code documentation is not just pure introspection. Consider the diagram made for the Padliography, a bookmarking system to collect links of otherwise scattered Etherpad documents. It describes not only what's happening in the code, but taps also into its surroundings: the Soupboat server and the XPUB and Lens Based Mediawiki instance.
Code documentation is not just pure introspection. Consider the diagram created for the _Padliography_, a bookmarking system for collecting links of otherwise scattered _Etherpad_ documents. It not only describes what's going on in the code, but also taps into its surroundings: the _Soupboat_ server and the _XPUB and Lens Based wiki_.
The introduction to a program situates it 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 introduction to a program situates it 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 rather than a web-based 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)
Their book _Aesthetic Programming - A Handbook of Software Studies_, is an example of how documentation can be a loom where to weave together technical and critical thinking. 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 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.
Their book _Aesthetic Programming - A Handbook of Software Studies_, is an example of how documentation can be a loom for weaving together technical and critical thinking. The book explains basic concepts of programming, starting from variables and loops, and moving on to more complex topics such as machine learning and speech recognition. The technical curriculum on offer is in line with other similar resources aimed at beginners. What's different here is the 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 publication for a public familiar with software studies discourses. Thanks to the vantage point of writing documentation for beginners, they could be super-explicit and go all out with a generous amount of references.
For hatching programmers, the initial imprinting of documentation is a powerful tool to orientate code in the world.
For hatching programmers, the initial imprinting of documentation is a powerful tool to orientate code in the world.
### A code companion
### 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.
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 operating system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just about knowing a programming language by heart, 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.
Documentation is not just for beginners: it's a code companion. You never stop reading it. Even experienced programmers must consult the docs when first encountering a software, and return to it when they need a refresher on the syntax of a particular command. They are continuously looking at code from multiple distances: close to the source code through lines of comment, 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 tentacular surface can reach a programmer at different moments of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the variety of forms that documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring diagrams and drawings. Daniele Procida proposes a systematic approach to organise this wealth of formats (2017). His framework focuses on the needs of different types of readers: by leveraging between practical steps and theoretical knowledge, he charts four main modes of technical writing. Each format has its own approach and intentions, and answers different questions.
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. _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 doesn't consider who's reading it can result inaccessible and frustrating. Although the Diataxis framework doesn't encompass every particular situation, its structure is a good aid to situate documentation within different perspectives. This turns out to be very helpful in the writing process, as a way of fine-tuning tones, and modulating the nature of shared information. _Tutorials_ open 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.
Or rather, the same documentation, for the same reader, for the same code, just at different moments in their life. Programmers' needs gradually change, as well as the answers they are looking for, but still, they keep returning to read the docs.
Or rather, the same documentation, for the same reader, for the same code, just at different moments in their life. Programmers' needs change over time, as do the answers they are looking for, but still, they keep returning to read the docs.
