code documentation as a publishing surface to create entry points?
!!! note "code documentation as a publishing surface to create entry points?"
yes but
it should stop assuming reader - see natural readers
@ -11,19 +10,13 @@ yes because
it's often first thing one reads when approaching software - see getting started
it's consulted not just from beginner, but also experienced users - see a code companion
```
```note
for structure:
1. Entry points
!!! note "for structure: entry points"
Researching languages, formats and approaches of code documentation to broaden participation in the making of software
1. Natural readers
2. Welcoming writing
3. Docs as gardening
4. Getting startled
5. Code companion
```
### 1.1 "Natural" reader
@ -35,9 +28,7 @@ Whenever too much technical proficiency is required to even read documentation i
To cultivate legibility is but an easy task, especially when dealing with computer technology: a cards castle of abstractions built on top of other abstractions.
```note
need abstraction example
```
!!! note "need abstraction example"
These abstractions are more than just metaphors: they are interconnected narrations and entwined plots and main characters at the same time. The purpose of an abstraction is to act as a symbol, as a mentally maneuverable concept, free from its technical implementation details. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up for the digital stack.
@ -48,9 +39,8 @@ A deep understanding of technical systems is admirable and desirable of course,
A different kind of approach, more modelled on the way technology and coding meet us in real life, starts from the middle and tries to make sense of its surroundings. One could just need to make a website, for example. And could just start doing that, following a guide or a tutorial. Soon questions would start bubbling up. Made from scratch or with a framework? And which one to choose? What about the backend? Where to host it? On which kind of server? Static or dynamic? And the Content Management System to upload new materials? And where to get the certificate for secure connection?
```note
wrap up example: no need to understand every single aspect to put the website online
```
!!! note "wrap up example:"
no need to understand every single aspect to put the website online
The series _Programming Projects for Advanced Beginners_ by Robert Heaton embrace this methodology. Each projects offers some guidance through the different steps involved when coding a particular application: a login system, a simple game, a graphic filter to apply to the webcam, etc.
@ -63,9 +53,7 @@ The entry points here are multiple as the spokes in a bicycle wheel. They come f
A lesson can be learned: sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about everything at the same time. Programming means to balance between these different aspects depending on the situation. Keeping it in mind when writing code documentation gives to the writer space to adjust tone, intensity and approach based on who is going to read these docs.
```note
wrap up the comparison between these two approaches
```
!!! note "wrap up the comparison between these two approaches"
It's not only a matter of contents and approach to technicalities, but also the very language with which they are formulated and exposed.
@ -79,9 +67,8 @@ In her books, she reports how the presence of female figures was distributed in
Many episodes in her writings describe interactions with coworkers where she is directly attacked because being a woman daring to enter the (total dudes situation of) technical zone of engineering. Or a client harassing her while she was working to fix his database. Or the segregation of _cheap latinas workers_ hired to do mechanical data entry in the room next to the mainframe's one, where all the other guys were gathered.
```note
!!! note ""
"Workers leaving the Googleplex" present this same last situation more than twenty years later, with Google pushing minorities towards subaltern unskilled work. See: http://www.andrewnormanwilson.com/WorkersGoogleplex.html
```
This condition is reflected also in the pages of code documentation. Technical manuals and software specifications have been addressed, and written from the point of view of, this very specific public, populated mainly by male engineers.
@ -185,15 +172,11 @@ Documentation is a surface where all the sociality, relations, and context aroun
A surface that in turn can be activated and used as a platform to reach all the different actors surrounding it.
```placeholder
like a backdoor!!
```
!!! placeholder "like a backdoor!!"
### 1.4 Getting started
```note
("Getting startled" could also make for a nice title)
```
!!! note "("Getting startled" could also make for a nice title)"
Reading undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code.
