@ -111,11 +111,6 @@ this can happen for several different reasons, two of them apparently at the opp
problems of contents:
problems of contents:
expect
- expert, formerly educated reader
- takes for granted the technical level of reader
- takes for granted a specific lexicon,
- refer to a broader context or previous, not explicit references
- see programming for the millions (ullman, 2016)
- see programming for the millions (ullman, 2016)
<!-- Code documentation tends to assume a certain kind of reader. This reader is often thought as similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cut through the precise lingo and esoteric references offered as explanation. 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. -->
<!-- Code documentation tends to assume a certain kind of reader. This reader is often thought as similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cut through the precise lingo and esoteric references offered as explanation. 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. -->
@ -134,6 +129,7 @@ there are some catches though: this is not a tutorial, but an entire university
many code documentations resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, and so on programming is the perfect rabbit hole because of the depth and complexity of each layer that make up for the digital stack
many code documentations resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, and so on programming is the perfect rabbit hole because of the depth and complexity of each layer that make up for the digital stack
<!-- Programming is a rabbit hole, and one can wander endlessly searching for where to start from. There is always something more low-level, something to understand before trying to understand the current system you are dealing with. -->
<!-- Programming is a rabbit hole, and one can wander endlessly searching for where to start from. There is always something more low-level, something to understand before trying to understand the current system you are dealing with. -->
bottom-up / top-down
bottom-up / top-down
a different kind of approach is more modelled on the way technology and coding confront us in real life. one often starts from the middle.
a different kind of approach is more modelled on the way technology and coding confront us in real life. one often starts from the middle.
@ -151,23 +147,32 @@ sometimes code is about performance, sometimes is about flexibility, sometimes i
2 problems of language:
2 problems of language:
- gendered writing and gendered roles
not only technical problems, but also how they are formulated
- developer often addressed as he/him
- dude culture and toxic masculinity
usage of language in technical documentation refer to a particular context
- example machism, vvvv twitter-api help patches
<!-- 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. -->
- example encoded chauvinism
mainly address male reader and gendered roles
<!-- Historically, technical manuals and software specifications have been addressed to a very specific public of male engineers. -->
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.
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."_ -->
Historically, technical manuals and software specifications have been addressed to a very specific public of male engineers.
<!-- 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. -->
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."_
discussions around gender neutral documentation
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.
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]
Target to reach vs public to create?
```note
```note
@ -177,13 +182,10 @@ A couple of brainstorming paragraphs feel free to skip sorry for the inconvenien
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.
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.
Target to reach vs public to create
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.
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.
Coding means to express ideas with the reduced vocabulary of a programming language.
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.
