Researching languages, formats and approaches of code documentation to broaden participation in the making of software
Researching languages, formats and approaches of code documentation to broaden participation in the making of software
1. Natural readers
1. Natural readers
2. Programming Language
2. Welcoming writing
2. Welcoming writing
3. Docs as gardening
3. Docs as gardening
4. Getting startled
4. Getting startled
5. Code companion
5. Code companion
### 1.1 "Natural" reader
### "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.
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.
@ -37,11 +38,7 @@ Take a course such the one presented by Noam Nisan and Shimon Schocken in _From
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 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.
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 example. 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?
!!! note "wrap up example:"
no need to understand every single aspect to put the website online
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 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.
@ -53,20 +50,19 @@ The entry points here are multiple as the spokes in a bicycle wheel. They come f
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.
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
!!! note "wrap up the comparison between these two approaches"
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 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, civil and military research labs and IT companies, were mostly frequented by white dudes.
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 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.
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 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.
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 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)
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 latinas workers_ hired to do mechanical data entry in the room next to the mainframe's one, 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
