diff --git a/bibliography.md b/bibliography.md index 244269b..ed92ba1 100644 --- a/bibliography.md +++ b/bibliography.md @@ -27,12 +27,14 @@ - readthefuckingmanual.com. (n.d.). _Read the Fucking Manual._ [online] Available at: http://readthefuckingmanual.com/ - Ullman, E. (2017). _Life in code : a personal history of technology._ New York: Mcd, Farrar, Straus And Giroux. - Ullman, E. (1997). _Close to the machine : technophilia and its discontents._ London: Pushkin Press. +- Shirky, C. (2004). _Situated Software_. [online] Available at: https://gwern.net/doc/technology/2004-03-30-shirky-situatedsoftware.html - Snelting, F. et al (2022). _A Wishlist for Trans\*femminist Servers._ [online] Available at: https://etherpad.mur.at/p/tfs - Soon, W. and Geoff Cox (2020). _Aesthetic programming : a handbook of software studies._ London: Open Humanities Press. - vuejs.org. (2021). _Lifecycle Hooks | Vue.js._ [online] Available at: https://vuejs.org/guide/essentials/lifecycle.html - 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/) ## License diff --git a/chapters/00_intro.md b/chapters/00_intro.md index 7d793fd..8e2c2f9 100644 --- a/chapters/00_intro.md +++ b/chapters/00_intro.md @@ -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. diff --git a/chapters/02_backdoors.md b/chapters/02_backdoors.md index c9bbf46..cb52783 100644 --- a/chapters/02_backdoors.md +++ b/chapters/02_backdoors.md @@ -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. +![A raspberri pi 4 with a composable case made with four plastic layers: red yellow green and blue, and with custom 3d printed legs](../img/soupboat.jpg "Figure 15. Soupboat, the server of our XPUB group. With 3d printed legs to run faster.") + +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. + + +```NGINX +# labsong - songs for difficult grad labor + +location ^~ /labsong/ { + proxy_pass http://localhost:3157/soupboat/labsong/; + include proxy_params; +} + +# 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. -![Hand holding an A4 sheet with a list of functions, relative descriptions and barcode to scan. In the other hand a barcode scanner. Clipped: a small receipt with printed the barcode for playing the radio.](../img/2022-04-04-brendan_humor.jpg "Figure 15. Menu printed by the Inhuman Resources bureau using the docstrings from the other offices. 4-4-2022 Workshop with Brendan Howell at XPUB") +![Hand holding an A4 sheet with a list of functions, relative descriptions and barcode to scan. In the other hand a barcode scanner. Clipped: a small receipt with printed the barcode for playing the radio.](../img/2022-04-04-brendan_humor.jpg "Figure 16. Menu printed by the Inhuman Resources bureau using the docstrings from the other offices. 4-4-2022 Workshop with Brendan Howell at XPUB") 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. -![Screenshoot of a Jupyter Lab IDE](../img/SI16_NB.jpg "Figure 16. Soupboat server. Jupyter Notebook of the repeat function. On the left panel the filesystem with the other function files.") +![Screenshoot of a Jupyter Lab IDE](../img/SI16_NB.jpg "Figure 17. Soupboat server. Jupyter Notebook of the repeat function. On the left panel the filesystem with the other function files.") -![Technical documentation showing on the left side parameters, and on the right the returning values.](../img/SI16.jpg "Figure 17. Documentation generated from the Notebook files for the Repeat function") +![Technical documentation showing on the left side parameters, and on the right the returning values.](../img/SI16.jpg "Figure 18. Documentation generated from the Notebook files for the Repeat function") -![The picture of a parrots and description of the function.](../img/SI16_2.jpg "Figure 18. Documentation of the Repeat function.") +![The picture of a parrots and description of the function.](../img/SI16_2.jpg "Figure 19. Documentation of the Repeat function.") 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. diff --git a/cover.md b/cover.md index 7f39f3e..d3c31a6 100644 --- a/cover.md +++ b/cover.md @@ -1,10 +1,10 @@ -Francesco Luzzana +__Francesco Luzzana__ # Hello Worlding _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. -Adviser Marloes de Valk -Second Reader: Lidia Pereira -Word count: 7953 +Adviser: __Marloes de Valk__ +Second Reader: __Lidia Pereira__ +Word count: 8182 diff --git a/img/soupboat.jpg b/img/soupboat.jpg new file mode 100644 index 0000000..1fdb6be Binary files /dev/null and b/img/soupboat.jpg differ diff --git a/notes.md b/notes.md index 448ac03..7feee43 100644 --- a/notes.md +++ b/notes.md @@ -5,8 +5,8 @@ [x] transition to getting startled from entry point to backdoor [x] example paragraph padliography situate within larger context [x] and maybe connect it to aesthetic programming -[x] outro code companion wrap up -[ ] outro +[x] outro code companion wrap up +[x] outro [ ] context soupboat in appendix / situated docs? [ ] readme in appendix / situated docs [x] hello worlding: code documentation as an entry point / backdoor to programming practices