@ -105,18 +105,18 @@ Message in console printed by Bridle to welcome users - source: booktwo.org
### 1.4 "Natural" reader
documentation that assumes a certain kind of reader can result inaccessible.
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.
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
problems of contents:
When it comes to contents, the 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.
When too much technical proficiency is required to even read documentation itself, knowledge results inaccesible and confined in an ivory tower. An important detail to notice here is that this is an antipattern, and 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.
- 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. -->
Exploring
too much technical knowledge is required to read the documentation itself.
the docs results impossible to read, and there is no knowledge one can make out of it if not already educated. not filtering knowledge becomes a filter to who can access it.
programming means building abstractions on top of abstractions, ad libitum.
@ -195,24 +195,39 @@ When the docs does not reflect the behavior of the project, or when there are di
There's a moltitude of ways in which changes in the codebase reflect on the documentation. New features ask for new sections. Breaking changes with previous versions require warnings and instructions on how to migrate towards the new one. Bugs and unexpected behaviours are to be addressed. Deprecated functions need to be trimmed out, or marked as outdated.
On top of all the technical aspects, the editorial work has to be taken into accounts. Adjustments and corrections and line-editing, clarification of convoluted paragraphs, rephrasing of confused sentences, highlighting of important passages. Certain projects also 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.
[and design]
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.
It's a process that requires a massive amount of energy and resources. Yet, it seems to be constantly understimated, undervaluated, and pushed towards the margins. Something left for when there's nothing better to do, something to delegate. Something perceived as a burden, as a killjoy, a display of weakness from _real programmers_ that should be able to understand a program by directly reading the sourcecode.
It's a process that requires a massive amount of energies and resources. Yet, it seems to be constantly understimated, undervaluated, and pushed towards the margins. Something left for when there's nothing better to do, something to delegate. Something perceived as a burden, as a killjoy, a display of weakness from _real programmers_ that should be able to understand a program by directly reading the sourcecode.
```note
not super happy with the references for the part about gendered work, would prefer to have more recent accounts. could be something left open for a next episode?
not super happy with the references for the part about gendered and subaltern work, would prefer to have more recent accounts, or more specific.
could be something left open for a next episode?
```
```placeholder
documentation as gendered labour, and subaltern labour. examples: excerpt from pattern of software (all programmers are male, all technical writers are female), excerpt from life in code (tech conference public).
```
all these effort are a confirmation of what proposed by the post meritocracy manifesto: the making of software is not just programming. the makers of software are not just engineers.
Writing documentation is perceived as subaltern labour.
- gendered labour
- reports from ullman about tech fairs: women just present at documentation related events
- accounts on Lucid by Richard Gabriel: female documentation manager, female technical writers
- subaltern labour
- typical pattern of tech industry?
- same as data entry,
- see ullman - close to the mainframe
- see workers leaving the google plex ? it'S a slightly different context?
All these effort are a good display of what advocated in the Post-Meritocracy Manifesto by Coraline Ada Ehmke and more than other six hundred signatories: the making of software is not just a matter of engineering skills, but interpersonal relations and social dynamics, where all the contributions around code are important as the one on the code itself.
Documentation is a surface where all the sociality, relations, and context around code are rendered visibile. An interface between the technical world of the machine, the affective sphere of the community, the delicate and demanding economies of open source projects, and the politics of distribution, circulation and participation in the making of software.
Documentation is a surface where all the sociality, relations, and context around code are rendered visibile. An interface between the technical world of machines, the affective sphere of the community, the delicate and demanding economies of open source projects, and the politics of distribution, circulation and participation in the making of software.
a surface that in turn can be activated to reach the different kinds of actors that surround it. kinda like a backdoor
A surface that in turn can be activated and used as a platform to reach all the different actors surrounding it.
