@ -8,7 +8,7 @@ Whenever too much technical proficiency is required to even read the documentati
Cultivating legibility is not an easy task, especially when it comes to computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narratives and intertwined plots and main characters at the same time. The purpose of an abstraction is to function as a symbol, as a mentally manoeuvrable concept, free from the details of its technical implementation. 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 the digital stack.
Cultivating legibility is not an easy task, especially when it comes to computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narratives and intertwined plots and main characters at the same time. The purpose of an abstraction is to function as a symbol, as a mentally manoeuvrable concept, free from the details of its technical implementation. 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 the digital stack.
@ -16,70 +16,64 @@ Take a course such as the one presented by Noam Nisan and Shimon Schocken in _Fr
A deep understanding of technical systems is of course admirable and desirable, given the insights it can provide into the infrastructures that shape 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 a barrier for many 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 deep understanding of technical systems is of course admirable and desirable, given the insights it can provide into the infrastructures that shape 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 a barrier for many 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.
A different kind of approach, more modelled on the way we encounter technology and coding in real life, starts in the middle and tries to make sense of its surroundings. You might just need to make a website, for example. And you could just start doing that, following a guide or a tutorial. Soon questions would start bubbling up: written from scratch or with a framework? And which one to choose? What about the backend? Where to host it? On what kind of server? Static or dynamic? And the _content management system_ for uploading new material? And where do you get the certificate for secure connection? These things certainly are important, but it is not really necessary to know everything in order to put the website online. Programming is provisional: leave TODOs in the code to come back to 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.
The series _Programming Projects for Advanced Beginners_ by Robert Heaton embraces this methodology. Each project offers some guidance through the different steps involved in coding a particular application: a login system, a simple game, a graphic filter to apply to the webcam, etc. A nice aspect of these guides is that they don't refer to a specific programming language: they are decoupled tutorials that leave the reader space to integrate and adapt the steps to their own coding contingencies, while at the same time helping to build a lexicon, teach how to search for informations, read error messages and find their way around. As in _NAND to Tetris_ things are built incrementally. Here, however, the process is iterative and circular, rather than linear. Implementations are put in place provisionally, and then reiterated, replaced and developed more: new concepts are introduced not as hard-coded procedures, but as a result of emerging problems. The entry points here are multiple, like 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 at play. Such kind of technical objects feel less monolithic and more approachable.
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.
A lesson can be learned: sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about all of these at once. Programming is about balancing these different aspects depending on the situation. Keeping this balance in mind when writing code documentation gives to the writer room to adjust the tone, intensity and approach depending on who will be reading these docs.
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 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 language
### 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.
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 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.
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.
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.
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 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)
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 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.
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 ""
!!! 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
"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.
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 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:
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."_
_"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.
This gendered language comes with an embedded division of roles.
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.
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 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.
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 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?
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?
### Welcoming writing
### 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.
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.
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).
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.
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](https://meta.stackexchange.com/a/93989) 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 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 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.
!!! note "spell checked till here"
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)
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.
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. (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 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 some examples that go in a different direction, on different scales.
Here some examples that go in a different direction, on different scales.
@ -109,6 +103,8 @@ There's a moltitude of ways in which changes in the codebase reflect on the docu
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.
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.
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.
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.
