@ -110,7 +110,7 @@ Not only to _find & replace_ terms throughout the documentation, but to re-trace
Writing documentation is demanding. It's more delicate than programming, and require a whole set of skills usually not treasured by the dev community. A kind of emotional intelligence and sensitivity far to be found in the competitive and pragmatical wastelands of the IT industry. Here no one wants to write documentation, nor pay someone to do it. As a result, in a world where software thrives, documentation still seems to be a scarce resource.
It's ok, someone could argue, every question that can be asked on Stack Overflow, will eventually be asked in Stack Overflow (versioning Atwood, 2007). The popular Q&A website for developers is just an example of digital knowledge as a shared effort, together with the endless mailing lists, forums, discord servers and dedicated sources for whatever topic. It's astonishing how online communities can tackle any problem in no time.
@ -143,11 +143,10 @@ When opening the browser inspector in the Facebook website, one faces a wall. A
`welcome.js` (2016) is a small gesture in response, a tiny Javascript library published open source on GitHub under a permissive MIT license, where Bridle injects some greetings in their website (and in all the websites that include the library) to welcome users to the browser inspector. The artwork is hidden below the surface of the website, printed in the console of the browser inspector, a tool which allows users to see underlying code of the website they are visiting. From here it provides some guidance for newcommers to access, inspect and modify the source code of web pages. A process to open doors and let people in, giving them more agency by demistifying technology.
Message in console printed by Facebook to stop users - source: booktwo.org
Message in console printed by Bridle to welcome users - source: booktwo.org
Whether in big project or small gesture, attention to language can be transformative. In code documentation it can help deconstructing the false dichotomy between programmer and user, or pro and newbie. It can create spaces that feel more safe, where people are invited to participate, express themselves and contribute to the community. It can help undoing the impostor syndrome that affects many programmer, and that feed on some hidden and inaccessible fundational knowledge nowhere to be found in code documentation. It can help to cast some light onto the massive amount of work around the making of software: recognizing all contributions, not just the ones from engineers.
@ -184,6 +183,11 @@ At the very first encounter with a new script, details about its source code are
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)
The initial imprinting of documentation is a vantage point to orientate code in the world.
@ -196,7 +200,7 @@ Documentation is not just for beginners: it's a code companion. One never stops
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 (Procida, 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 knowledge around code in a way that tries to meet every user possible. _Tutorials_ offer entry points for the newcomers, while _explanations_ unveal 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.
@ -77,7 +77,7 @@ Who wants to use the API needs to come at terms with the conditions detailed in
One example is the paradigm of constant availability of the server. Behind every _SaaS_ there are always one or more servers: the so called _someone else's computer_ working behind the scenes. The seamless picture of cloud of big techs rarelly includes these machines, that are abstracted away and hidden from the user. In the Queer Motto API instead the presence of the server is a key aspect, especially when it decides to take a nap or refuses to work for strike. These behaviors are documented with different error codes, offering a way for the developers using the API to make their applications react accordingly, or even join the cause.
!!! note ""
@ -139,7 +139,7 @@ a workbook dedicated to the alternative text descriptions that make web images a
Websites are made of HTML, a markup language composed of tags. Each tag represents an element of the document: a header, a paragraph, a link to another page, an image, and so on. As in a sandwich, these tags can be composed together, and organized to structure the contents of a web page. Every tag comes with particular attributes, and the image `<img>` one requires the developer to specify the source `src` of the picture to display. Here is also possible, but not technically mandatory, to add an `alt` attribute, with the alternative description of the image used by screen readers and other assistive technologies.
```html
<imgsrc="../img/workbook.jpg"alt="Big text fills the cover: ALT-TEXT AS POETRY. Each letter is made of repeated round shapes. The cover is printed on a subdued green paper, the inside pages are a soft white color, and the whole book is bound with a plastic, forest green spiral coil.">
@ -153,11 +153,7 @@ The `p5.js` library for example offers a `describe()` and `describeElement()` fu
In the discussions around the development of this open source project, contributors started considering how to encourage the usage of this function. From an initial suggestion of making it a requirement in order for sketch to run, opinions settled on conveying its importance from the documentation, by adding it to the default template, and to the examples in the documentation and tutorial.
Examples from p5.js documentation.
from my side: last year when developing my space on the soupboat i decided not to display images if they don't come with alt text
decision like these aren't really different from how a type system work, or how the syntax of a certain function is written. everything has been decided by someone. these decisions can create or claim new and safe spaces for participating to programming practice, or validate this participation
@ -204,8 +200,7 @@ class Humor(Bureau):
```
Sample from `jokes.py`, the module of the _Department of Humor_. Here two _docstrings_ describe the bureau itself and the `Fortune Cookie` command.
Menu printed by the Inhuman Resources bureau using the docstrings from the other offices, ready to be invoked with the barcode-scanner. _4-4-2022 Workshop with Brendan Howell at XPUB_
In the essay _Chimeric Worlding_, researcher and designer Tiger Dingsun explores what can graphic design learn from poetics to escape a condition of pure functionalism. Graphic design and code documentation are similar: both deal with organizazion and presentation of information, making meaning through configuration of various element which are not just limited to language and text, but also might include images, symbols, (code snippets, examples). With a `find&replace` to swap all the occurences of `graphic design` to `code documentation`, Dingsun's essay can be versioned to get an interesting perspective on what's happening in the Screenless Office.
