- XPUB (2022). _Learning How to Walk while Catwalking._ [online] Available at: https://issue.xpub.nl/16/
- XPUB (2022). _the-screenless-office. XPUB GIt._ [online] Available at: https://git.xpub.nl/kamo/the-screenless-office
## List of figures
1. Code documentation flows, with a roster and a barn owl.
@ -49,10 +51,11 @@
12. Response from the Queer Motto API with refusal message. source: [gitlab.com/siusoon/queer-motto-api](https://gitlab.com/siusoon/queer-motto-api)
13. Alt-text as poetry workbook, and relative image tag with alt description. source: [bombmagazine.org](https://bombmagazine.org/articles/bojana-coklyat-and-shannon-finnegan-interviewed/)
14. Examples from p5.js documentation. source: [p5js.org](https://p5js.org/)
15. Menu printed by the Inhuman Resources bureau using the docstrings from the other offices. source: [4-4-2022 Workshop with Brendan Howell at XPUB](https://media.xpub.nl/2022/2022-04-04-brendan.mp4)
16. Soupboat server. Jupyter Notebook of the repeat function. On the left panel the filesystem with the other function files.
17. Documentation generated from the Notebook files for the Repeat function. source: [issue.xpub.nl/16](https://issue.xpub.nl/16/)
15. Soupboat, the server of our XPUB group. With 3d printed legs to run faster."
16. Menu printed by the Inhuman Resources bureau using the docstrings from the other offices. source: [4-4-2022 Workshop with Brendan Howell at XPUB](https://media.xpub.nl/2022/2022-04-04-brendan.mp4)
17. Soupboat server. Jupyter Notebook of the repeat function. On the left panel the filesystem with the other function files.
18. Documentation generated from the Notebook files for the Repeat function. source: [issue.xpub.nl/16](https://issue.xpub.nl/16/)
19. Documentation generated from the Notebook files for the Repeat function. source: [issue.xpub.nl/16](https://issue.xpub.nl/16/)
@ -18,7 +18,6 @@ Documentation broadens participation in the making of software: lowering barrier
`Current #2`
Documentation as a backdoor where to inject context into software: to host principles in close contact with algorithms, letting them entangle and shape each other.
The nature of code documentation is to create entry points for people to participate in programming practices. To encode and filter knowledge, and ultimately to share it with others. This "nature", however, does not come without issues. It makes a lot of assumptions about who's reading, expecting experts, or engineers, or dudes. Its language is unwelcoming: too dense, too technical, very gendered and unable to address anyone but the neurotypical-white-cis-male programmer. Documentation requires an enormous amount of care, energy and time to be maintained, and it's done always out of budget, always as a side project, always at the end, and only if there's time left. The first chapter raises these points to note how often code documentation acts as a barrier, gatekeeping access to the making of software.
Even if it does a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface whose reach extends through time and space. Time because it meets programmers at different moments in their lives: from the _hello world_ till the _how to uninstall_, and it influences thinking about software continuously, and from different perspectives. Space because it comes in many different possible formats, and can shapeshift to serve different occasions: from simple `.txt` files to entire websites, from coding workshops to comments in the source code to series of video tutorial.
@ -80,7 +80,47 @@ _360 degrees of proximities_ is a project emerging from a network of feminist se
After sucessfully setting up of a self-hosted Peertube instance, a federated platform for sharing video content, the group began to question aspects of maintaining the system. Rather than centralising the service in a self-exploitative scenario, they decided to redistribute responsability across the network, working with other feminist and queer communities and empowering them to build their own video platforms autonomously, but in a joint effort. This is where different knowledges meet: on one hand the know-how about installation and configuration of Peertube brought by the _360_ team, and on the other site-specific knowledge of the hosting server.
This is where the interesting friction of situated documentation arises: how to share knowledge about deeply situated programming practices with other contexts? How to remain legible and accessible, for ourselves and for others, while at the same time preserving specific and characteristic decisions? Usually documentation doesn't take into account the messiness of coding contingencies, where multiple software coexist on the same server and configurations conflict or are installed with different setups. Collective learning moments can bridge the gap between the default setup described in documentation and a real-world, situated one.
From the perspective of hosting others into "our" code, documentation becomes a form of hospitality. A form of care for a shared space. In XPUB, each group begins its two-years programme by setting up a self-hosted server. We called ours [Soupboat](https://hub.xpub.nl/soupboat/), and it houses many of our prototypes and experiments. This small server, running on a Raspberri Pi, feels like a place to call home on the internet. Over the past two years we have done all sorts of projects there: generated web-to-print publications, custom CMSs to manage birthdays, Etherpad documents, and soup recipes, workshops, personal wikis, and so on. While living on a server with others, my approach to code began slowly to change. Publishing open git repositories, instead of hiding behind private ones. Writing more readme files to be more generous with friends and colleagues and tutors. Cultivating small gestures and rituals, like leaving comments in config files to remind others where to mount the next app or where to find some credentials.
# ATTENTION: use port 3158 for the next project!!!! ;))
```
_NGINX configuration with gentle, incremental reminder on which port to use for the next app_
At the same time, this awareness grew by acknowledging the particular context of this small setup, of this _situated software_ (Shirky, 2004).
In many readme for example, such as the one for the networked drawing app [drw](https://git.xpub.nl/kamo/drw) or the [padliography](https://git.xpub.nl/kamo/pad-bis), the explanations are tailored specifically for the Soupboat, and they cannot probably be ported 1:1 somewhere else. Nonetheless, the space is prepared for hosting new guests.
```md
Eventually you want to put online your drawing app.
To be able to use this app on the Soupboat (or other servers connected in the hub.xpub.nl ecosystem) some additional configurations are needed.
Note that the following details are tailored to the particular case of our server. Other instances could require different setups.
This is one possible workflow.
Clone the repo and install the requirements as you would do locally.
git clone https://git.xpub.nl/kamo/drw
cd drw
npm install
```
_Notes from drw's readme._
This is where the interesting friction of situated documentation arises: how to share knowledge about deeply situated programming practices with other contexts? How to remain legible and accessible, for ourselves and for others, while at the same time preserving specific and characteristic decisions? Usually documentation doesn't take into account the messiness of coding contingencies, where multiple software coexist on the same server and configurations conflict or are installed with different setups. Collective learning moments and small, shared rituals can bridge the gap between the default setup described in documentation and a real-world, situated one.
### Hello worlding
@ -122,7 +162,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.
In the essay _Chimeric Worlding_, researcher and designer Tiger Dingsun explores what graphic design can learn from poetics to escape a condition of pure functionalism. Graphic design and code documentation are similar: both deal with the organizazion and presentation of information, making meaning through the configuration of different elements, which are not just limited to language and text, but can also include images, symbols, (code snippets, examples). With a find&replace to swap all 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.
@ -142,10 +182,10 @@ Tipically an API's architecture is centralised: there's a grand scheme and every
SI16 has been a space for undoing the grand scheme and let a plural, vernacular autorship to emerge. On the server side the API is structured as a filesystem, and to insert a new function it's enough to upload a Jupiter Notebook file containing the script and its documentation. Jupiter Notebooks are interactive documents in which code snippets and their explanations can be interwoven. They come handy for prototyping and documenting learning processes, writing code to be read not only by computers, but also by other programmers, 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 the technical be confident, be ambitious, and be ready to fail a lot. With these notebooks we were able to keep different voices visible in the documentation, to question a rigid and centralised structure, creating space to document and code from multiple perspective.
_Code documentation as entry point / backdoor to programming practices._
Thesis submitted to the Department of Experimental Publishing, Piet Zwart Institute, Willem de Kooning Academy, in partial fulfilment of the requirements for the final examination for the degree of: Master of Arts in Fine Art & Design: Experimental Publishing.
