code documentation as a publishing surface to create entry points?
code documentation as a publishing surface to create entry points?
yes but
yes but
it should stop assuming reader - see natural readers
it should stop assuming reader - see natural readers
@ -29,8 +29,6 @@ Researching languages, formats and approaches of code documentation to broaden p
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.
a.
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.
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.
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.
@ -48,13 +46,11 @@ 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 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
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.
wrap up example: no need to understand every single aspect to put the website online
```
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?
[...]
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.
@ -75,20 +71,24 @@ A lesson can be learned: sometimes code is about performance, sometimes is about
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.
The language of technical documentation talks to a really particular public. This public has historically been addressed as male, and as belonging to a white, formerly educated, whealthy background.
Historically, technical manuals and software specifications have been addressed to a very specific public of male engineers. A really particular public, probably originated by the overlapping of cost and accessibility of higher education in USA, together with a patriarchal and segregated society model. The places where software was developed, universities and IT companies, were frequented only by whealthy white dudes.
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.
mainly address male reader and gendered roles
[example]
<!-- Historically, technical manuals and software specifications have been addressed to a very specific public of male engineers. -->
mainly address male reader and gendered roles
see gettext, karayanni, read the feminist manual
see gettext, karayanni, read the feminist manual
<!-- 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."_ -->
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."_
<!-- As Mara Karayanni argues in _Read The Feminist Manual_, published under 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. -->
As Mara Karayanni argues in _Read The Feminist Manual_, published under 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
discussions around gender neutral documentation
@ -100,6 +100,8 @@ vvvv evvvvil patches and documentation
[need conclusion and link to next section]
[need conclusion and link to next section]
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.
