The nature of code documentation is to create entry points for people to participate in programming practices. This "nature", however, comes not without issues: due to assumptions on who is reading the documents, the approaches, language, and tone used to illustrate the contents, and the amount of time and energies required for maintenance. These problems are addressed in the first part of this section.
Even doing a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface that stretches through time and space. Time because it meets programmers in different moments of their life: when they are moving their first steps and are just beginners, as well as when they are more navigated and need some specific references. Space because it comes with many different possible formats, and can shapeshift to serve diverse occasions. The question then is: can we make use of these backdoors to infiltrate programming practice and open more entry points from the inside?
Even doing a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface that stretches through time and space. Time because it meets programmers in different moments of their life: when they are moving their first steps and are just beginners, as well as when they are more navigated and need some specific references. Space because it comes with many different possible formats, and can shapeshift to serve diverse occasions, would it be a tutorial, a workshop, a printed manual. The question then is: can we make use of these backdoors to infiltrate programming practice and open more entry points from the inside?
### "Natural" reader
Documentation that assumes a certain kind of reader can result inaccessible. This can happen for several different reasons, two of them apparently at the opposite spectrum of the problem: the very contents of documentation and the language with which these contents are exposed.
When it comes to contents, the reader is often thought similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cutting through the precise lingo and esoteric references offered as explanations. Eventually (and in most of the cases) who's reading happen to be someone else. This mismatch transforms entry points into barriers that filter out who can participate to coding.
Documentation that assumes a certain kind of reader can result inaccessible. The recipient is often thought similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cutting through the precise lingo and esoteric references offered as explanations. Eventually (and in most of the cases) who's reading happen to be someone else. This mismatch transforms entry points into barriers that filter out who can participate to coding.
Whenever too much technical proficiency is required to even read documentation itself, knowledge results inaccesible and confined in the ivory tower. An important detail to notice here is that this is an antipattern that reinforces the segmentation between who is allowed in and who is not: only previously educated ones can access, while others are kept out. Not filtering information becomes a filter to who can engage with it. Contents need to be curated, that does not mean over-simplified or generalized, but rather made legible.
@ -29,7 +29,7 @@ The main focus of this chapter is to explore software documentation as a surface
A way to situate programming in specific contexts.
!!! note "backdoor here"
### Documentation & distribution
@ -48,11 +48,24 @@ One example is the paradigm of constant availability of the server. Behind every
!!! note "SI16 API"
- SI16 API where ????
- horizontal and vernacular
- after queer motto api
- after screenless office because of docstrings? or maybe use docstrings here?
### Distributed autorship
_Learning How to Walk while Catwalking_ is a collective project we developed in the context of Special Issue 16. It is published as an API that offers a toolkit to explore natural language processing in a vernacular way. It makes available several _endpoints_ to experiment with text transformations in a playful way, from simple operations like repeating or filtering certain words in a writing, to more articulated projects to annotate images, or use words like _etc_ and _..._ as containers to enrich unfinished lists.
!!! note "Endpoint"
An endpoint is a location where the API receives requests for specific resources. Usually it's an URL. An example of endpoint is: `https://hub.xpub.nl/soupboat/si16/api/repeat/?text=hello×=3`, that call the `repeat` function in the server, passing a text to repeat `hello` and the amount of repetitions `3`
Tipically an API architecture is centralized: there's a grand scheme and everything must fit there, both code- and documentation-wise. Documentation guidelines such as the previously mentioned Diataxis Framework recomend to keep a consistent tone and to offer a single source of truth to navigate the codebase. These prompts sure are helpful to maintain legibility, but little they reveal about the inherent distributed autorship of code.
SI16 has been a space for plural, vernacular autorship to emerge. On the server side the API is structured as a directory, and to insert a new function it's enough to upload a Jupiter Notebook file with the script and its documentation. Jupiter Notebooks are interactive documents where code snippets and their explanations can be weaved together. They come handy for prototyping and documenting learning processes, writing code to be read not only from computers, but also from other programmers as well, in a paradigm also known as _literate programming_, introduced by Donald Knuth in 1984.
The title of the project was a declaration of intents: when approaching technicalities be confident, be ambitious, and be ready to fail a lot. Using these notebooks we were able to maintain different voices visible in documentation, questioning a rigid and centralized structure, creating space to (document) code from multiple perspective.
### Situated docs
@ -98,11 +111,6 @@ Inspired by Alt-text as poetry for example, I decided to write the code for the
```
_Code for the project pages on the soupboat. The figure with the header is added if and only if both cover and alt description are provided._
!!! note "proper description?"
what does it even mean "proper"
you are just checking if there is an alt or not
not checking quality
An implementation first approach however is not always an option, and code documentation is a more adeguate surface to work with. The `p5.js` library for instance offers a `describe()` and `describeElement()` functions, to provide a description analogue to the `alt` text one for their visual sketches. The interactive graphics are based on the HTML `canvas` element, that instead of dealing with its contents in a semantic way as HTML does, works on pixel bases. Similar to images, these contents are not compatible with screen readers, and require a text explanation in order to render accessible what's happening on the display. Even more: while images are usually static, p5.js visuals are often in motion, and evolve through time. With `describeElement()`, developers can even be more granular in their descriptions, captioning transformations of different elements in their animations.
