- Hanlon, J. (2018). Stack Overflow Isn’t Very Welcoming. It’s Time for That to Change. [online] Stack Overflow Blog. Available at: https://stackoverflow.blog/2018/04/26/stack-overflow-isnt-very-welcoming-its-time-for-that-to-change/.
- Fisher, M. (2013). Suffering With a Smile. [online] Available at: https://theoccupiedtimes.org/?p=11586 [Accessed 16 Feb. 2023].
- Norman Wilson, A. (2011). Workers Leaving the Googleplex. [online] Available at: http://www.andrewnormanwilson.com/WorkersGoogleplex.html
@ -60,72 +60,57 @@ Like in _NAND to Tetris_ things are built gradually. Here however the process is
The entry points here are multiple as the spokes in a bicycle wheel. They come from different directions and don't frame the code as a prescriptive and rigid system, but rather as a crafted balance between different forces and needs in play. This kind of technical objects feel less monolithic and more approachable.
A lesson can be learned: sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about everything at the same time. Programming means to balance between these different aspects depending on the situation. Keeping it in mind when writing code documentation gives to the writer space to adjust tone, intensity and approach based on who is going to read these docs.
```note
wrap up the comparison between these two approaches
```
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.
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, technical manuals and software specifications have been addressed to a very specific public, populated mainly by male engineers.
This really particular monoculture probably comes as a result of several overlapping factors: the prohibitive costs of higher education, the availability of foundings in really specific parts of the western world due to military research, 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 to subaltern and menial tasks.
Historically code documentation has been addressed to a very specific public. The places where software was developed back in the days, universities, civil and military research labs and IT companies, were mostly frequented by white dudes.
The places where software was developed, universities, 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 due to military research, 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 working as developer in the Silicon Valley during the 80s and 90s. The combination of coming from 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 some passages she reports how the presence of other female figures is distributed in the IT sector: while visiting conventions, women are to be found 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 are gathering of young men. (2016)
Many episodes in her writings describe interactions with coworkers where she is directly attacked because being a woman daring to enter the technical zone of engineering. Or a client harassing her while she was working to fix his database. Or the segregation of female workers belonging to a foreign minority hired for cheap to do data entry, mechanical work in the room next to the mainframe's one where all the other guys were gathered.
This gendered segregation of developers reflected also in the pages of code documentation. This gendered language comes with an embedded and gendered separation of roles. Consider the excerpt from the GNU `gettext`: _"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 her books, she reports how the presence of female figures was distributed in the IT sector: while visiting tech conventions, women were to be found 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 latinas 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
```
As Mara Karayanni argues in _Read The Feminist Manual_, published with Psaroskala Zine, the stubborness against gender neutral language in technical writing is but a pretext for refusing to waiver the priviledge of the male programmer.
discussions around gender neutral documentation
dude behaviours and toxic masculinity
vvvv evvvvil patches and documentation
<!-- vvvv is a visual programming language that offers an agile approach to prototyping, adoperated especially in the context of interaction design. It's focused on rapid and iterative work of fine tuning, necessary when dealing with real time inputs, such as sensors, live data, or human interaction. -->
[need conclusion and link to next section]
This condition is reflected also in the pages of code documentation.
toxic geek masculinity reinforces stereotypes such as gendered roles in programming, or refuses to acknowledge the participation of diverse identities in the making of software. See gender neutral discussion, racist and discriminatory terms, dude behavior. this is reflected in documentation manuals.
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.
Target to reach vs public to create?
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:
```note
A couple of brainstorming paragraphs feel free to skip sorry for the inconvenience
```
_"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."_
Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers.
This gendered language comes with an embedded and gendered 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.
Learn to code is like learning another language: not just a new bag of words and a different grammar, but rather a different way to think. It means not just learning what are the things that move and the ones that are fixed, but also how they relate and make meaning together.
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.
Coding means to express ideas with the reduced vocabulary of a programming language.
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?
### 1.2 Welcoming writing
The potential of documentation to orientate software in the world clashes against some big elephants in the room, and tech culture should stop keep them in captivity. Sure, it would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available.
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 wastelands of the IT industry. Here no one wants to write documentation, nor hire someone to do it (Gabriel, 1996). As a result, in a world where software thrives, documentation still seems to be a scarce resource.
<!-- The potential of documentation to orientate software in the world clashes against some big elephants in the room, and tech culture should stop keep them in captivity. Sure, it would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available. -->
```note
unpack Gabriel
```
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.
@ -107,3 +107,14 @@ Think about projects related to accessibility, and space built by and for people
```placeholder
Think about the efforts to create safe spaces to learn.
```
```note
A couple of brainstorming paragraphs feel free to skip sorry for the inconvenience
```
Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers.
Learn to code is like learning another language: not just a new bag of words and a different grammar, but rather a different way to think. It means not just learning what are the things that move and the ones that are fixed, but also how they relate and make meaning together.
Coding means to express ideas with the reduced vocabulary of a programming language.
