@ -22,11 +22,11 @@ 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.
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](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle-diagram), 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.
For example [Vue.js](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle-diagram), a 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 and Soon, 2020)
@ -39,17 +39,19 @@ The initial imprinting of documentation is a vantage point to orientate code in
## 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.
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, and know how to adapt.
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 through 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 can reach a programmer in different moment of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the multitude of shapes documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring colored images. Daniele Procida proposes a systematic approach to organize this wealth of formats (diataxis.fr, 2017). His framework focuses on the needs of different kinds of readers: by leveraging between practical and theoretical knowledge it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
This tentacular surface can reach a programmer in different moment of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the multitude of shapes documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring colored images. Daniele Procida proposes a systematic approach to organize this wealth of formats (diataxis.fr, 2017). His framework focuses on the needs of different kinds of readers: by leveraging between practical steps and theoretical knowledge it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
This system organizes the knowledge around code in a way that tries to meet every user possible. The _tutorial_ offers entry points for the newcomer, while the _explanation_ reveals the core mechanism for the more navigated reader. The _how-to_ teaches how to get the work done, while the _reference_ reports a list of information ready to be consulted. Different documentation for different readers for the same code.
This system organizes knowledge around code in a way that tries to meet every user possible. _Tutorials_ offer entry points for the newcomers, while _explanations_ reveal core mechanisms for more navigated readers. _How-to guides_ teach how to get the work done, while _references_ report lists of information ready to be consulted. Different documentations for different readers for the same code.
The diataxis framework doesn't encompass every particular necessity or developer, but its two axis offer a good structure to situate documentation within different context.
A text that fails to address who's reading can result inaccessible and frustrating. Although the Diataxis framework doesn't encompass every particular situation, its two axis offer a good structure to situate documentation within different perspectives. This turns out to be really helpful in the process of writing, as a way to fine tune tones and modulate the amount of shared info.
The same is true for the additional layers of reading~meaning necessary for a process of world building. Enchanting software with political aesthetic (Ranciérre read through Soon and Cox, 2020) requires to operate at different scales. Public and private dimensions, within both technical and social framework.
```
notes:
@ -113,5 +115,3 @@ theory giving reference
```
The structure of diataxis is useful to navigate through the different needs of a reader, or through different readers at all.
Documentation that fails to address its reader can result inaccessible and frustrating.
