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. two different approaches here on how to deal with this intimidating stack of complexity.
programming means building abstractions on top of abstractions, ad libitum.
two different approaches here on how to deal with this intimidating stack of complexity.
one is sequential, from the ground up. see nand to tetris. from logic gates to a programmable comptuer. it gives insights on how a machine works starting from scratch.
@ -134,7 +136,7 @@ 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.
programming for advanced beginners series. decoupled tutorial: no specific language, but rather specific case studies to understand practically and first hand. here the series present a practical problem, such as how to code an _hygienic login system_. here like in nand to tetris things are built gradually. here however the process is iterative and circular, instead of linear. implementations are put in place provisionally and then reiterated and developed more, introducing new concepts not as hardcoded procedures but as a result of emerging problems.
programming for advanced beginners series. decoupled tutorial: no specific language, but rather specific case studies to understand practically and first hand. here the series present a practical problem, such as how to code an _login system_. like in nand to tetris things are built gradually. here however the process is iterative and circular, instead of linear. implementations are put in place provisionally and then reiterated and developed more, introducing new concepts not as hardcoded procedures but as a result of emerging problems.
the entry points here are multiple as the spokes in a bicycle wheel, as they come from different directions and don't frame the code as a prescriptive and rigid system, but rather as a crafted balance between different forces in play
@ -149,7 +151,7 @@ sometimes code is about performance, sometimes is about flexibility, sometimes i
not only technical problems, but also how they are formulated
usage of language in technical documentation refer to a particular context
usage of language in technical documentation refer to a particular context and public
<!-- 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
@ -195,7 +197,7 @@ documentation that does not reflect the behaviours of the code is a curse that u
- 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.
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 warnnings and 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.
@ -211,6 +213,6 @@ documentation as gendered labour, and subaltern labour. examples: excerpt from p
- 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.
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
