From 50ce512b0010574fd7c6cf491b2fe080fffc0ab0 Mon Sep 17 00:00:00 2001 From: km0 Date: Thu, 30 Mar 2023 09:05:08 +0200 Subject: [PATCH] 01 finale --- chapters/01_entry_points.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/chapters/01_entry_points.md b/chapters/01_entry_points.md index a084d46..bfcd516 100644 --- a/chapters/01_entry_points.md +++ b/chapters/01_entry_points.md @@ -195,12 +195,13 @@ 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, also 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, 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. -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. +[and design] -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 _use the source_. +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. ```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? @@ -209,9 +210,9 @@ not super happy with the references for the part about gendered work, would pref ```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. +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. -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. - -code documentation is a surface where all the sociality, context, and relations around software are visible. 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 to reach the different kinds of actors that surround it. kinda like a backdoor