From f25f844dd3dfcfcb72e37f44334cd06e1b7ae1cd Mon Sep 17 00:00:00 2001 From: km0 Date: Sat, 25 Mar 2023 23:56:04 +0100 Subject: [PATCH] documentation as gardening --- chapters/01_entry_points.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/chapters/01_entry_points.md b/chapters/01_entry_points.md index a5b4bf0..4cd4352 100644 --- a/chapters/01_entry_points.md +++ b/chapters/01_entry_points.md @@ -188,8 +188,27 @@ vvvv is a visual programming language that offers an agile approach to prototypi ### 1.5 Documentation as gardening - Code documentation require as much maintainance as code itself + +documentation that does not reflect the behaviours of the code is a curse that undermine the code reliability. docs are not once in a lifetime effort, but a continuous commitment. code transforms and documentation should adapt. + - Updates, corrections, additions, translations + +there are a moltitude of ways in which a change in the codebase reflects in the documentation. New feature asks for new sections. updates and breaking changes to with the previous versions require instructions on how to migrate to the new one. +bugs and unexpected behaviours of the code are to be pointed out. deprecated functions need to be trimmed. + +on top of that all the editorial effort has to be considered. corrections and line editing. internationalization and localization. + - Massive amount of energy required -- Gendered labour - Documentation as subaltern work (in open source projects) + +a massive and constant amount of energy and time is required. resources put into documentation projects are not that much. documentation work is understimated and undervaluated. + +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). + +[field work could be sooooo beneficial here like to search for contribution in docs repo] + - Post-meritocracy manifesto + +all these effort are a confirm 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