You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
123 lines
6.6 KiB
Markdown
123 lines
6.6 KiB
Markdown
# Who is reading
|
|
|
|
_why documentation as a surface to build worlds around software?_
|
|
_docs to lower barriers and create entry points_
|
|
|
|
```
|
|
a surface to build worlds?
|
|
where software circulate
|
|
who gets to use it
|
|
political of the software
|
|
|
|
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
|
|
|
|
yes but
|
|
it should stop assuming reader
|
|
it should be more welcoming for different kind of knowledges
|
|
|
|
leading to: 2. welcoming different knowledges
|
|
```
|
|
|
|
## Getting started
|
|
|
|
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.
|
|
|
|
At the very first encounter with a new script, details about its source code are unknown. Programming is a play _in medias res_, and documentation acts the role of narrator. Describing how functions are stitched together, or an algorithm is implemented, it sets the stage for developers to participate. Showing the different steps of a program and how they are connected, it offers entry points for interventions.
|
|
|
|
For example Vue.js, the popular library for building web user interfaces, explains with a diagram the lifecycle of its components: at which moment data are received from a server, at what point an element is rendered on screen, and when it will disappear. What at the beginning feels like magic, gradually appears more clear. Presenting a structure means also presenting a way to reason about it. The reader gains some understanding and agency over the tools they are about to use.
|
|
|
|
The introduction to a program situates it also within a larger ecosystem: how to install it, and what dependencies it requires to work properly. As Geoff Cox and Winnie Soon elaborate on their decision of a downloadable code editor instead of a web one for their classes, code is more than just a single piece of software. It is also the relations with the configuration of one's own computer and operating system. (Cox & Soon, 2022)
|
|
|
|
```
|
|
better transition above
|
|
better conclusion below
|
|
```
|
|
|
|
The initial imprinting of documentation is a vantage point to orientate code in the world.
|
|
|
|
## A code companion
|
|
|
|
The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the specifics of a particular programming language or platform. Sometimes for the web, sometimes for a hardware component, sometimes for another operative system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just knowing by heart a programming language, but rather having to deal with a lot of different recipes for different occasions.
|
|
|
|
Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering a software, and return to the references when they need a refresher on the syntax of a particular command. They continuously look at code from multiple distances: close to the source code with lines of comment—ignored by the machine, but much appreciated by fellows developers—or from printed books, along with pages of explanations and use cases.
|
|
|
|
This tentacular surface reaches different moments in the life of a programmer: from the _hello world_ to the _how to uninstall_.
|
|
|
|
- different documentations for different readers
|
|
- wrap up
|
|
|
|
### previous writings
|
|
|
|
- lowering barriers and creating entry points
|
|
- readme examples
|
|
- p5js debug examples
|
|
|
|
## Software without documentation
|
|
|
|
Software without documentation is invisible. Therefore it is important to document it. Software without documentation tends to slip away, to disappear. Therefore it is important to have some notes on how does it work, how does it tackle the problem to solve.
|
|
|
|
These guidelines are helpful when sharing programs with others, as well with future selves. They provide an entry into the messy relationship between developers and machine.
|
|
|
|
---
|
|
|
|
_bonus caption for images:_
|
|
|
|
Being programming slightly different from cycling, people tend to forget what their code does, and how did it get there. (Maybe because it doesn't involve muscle memory?)
|
|
|
|
Software documentation is a defensive mechanism operated from our past selves to protect the present and future ones.
|
|
|
|
Cuneiform writing and comments. (even though this is cuneiform writing and syntax highlighting)
|
|
|
|
## Different distances
|
|
|
|
Who is writing could be the very same developer or someone else. Writings come with different approaches and intentions, and as response to different needs.
|
|
|
|
## Different documentation for different readers
|
|
|
|
Documentation comes in many different forms. Daniele Procida offers a systematic approach to organize this wealth of formats (diataxis.fr, 2017).
|
|
|
|
His framework is built at the intersection of two axis: one goes from theoretical to practical knowledges, while the other from study to work. Here _study_ could be read as _learning_ or _understanding_, while _working_ means getting things done. Another powerful couple of synonims is _receiving_ and _giving_: by combining the renamed axis we can get a glimpse of the flow of knoweldge involved in documentation.
|
|
|
|
<!-- This could be a nice image to rework the diataxis: -->
|
|
|
|
```
|
|
practice receiving tutorial
|
|
theory receiving explanation
|
|
practice giving how to
|
|
theory giving reference
|
|
```
|
|
|
|
The structure of dyataxis is useful to navigate through the different needs of a reader, or through different readers at all.
|
|
|
|
So who's reading?
|
|
|
|
## Not for beginners
|
|
|
|
Documentation that fails to address its reader can result inaccessible and frustrating.
|
|
|
|
## who is reading?
|
|
|
|
- assuming a certain kind of reader - expert - dude
|
|
- references:
|
|
- programming for the millions (ullman, 2016)
|
|
- read the feminist manual (karayanni, 2021 )
|
|
|
|
## lowering barriers and creting entry points
|
|
|
|
- lowering barrier
|
|
|
|
- debugging (p5.js education working group, 2015)
|
|
- aesthetic programming
|
|
- readme examples?
|
|
|
|
- Problems with depth (too shallow or too deep)
|
|
|
|
- multiple entry points
|
|
- different entries make for different knowledges
|
|
- drawings and memes
|
|
- welcome.js (bridle, 2016)
|
|
|
|
that brings us to --> welcoming different knowledges
|