Code documentation is an interface between the code, the user, the developer, and the world. Living close to the source code, but at the same time being less rigid and more expressive, documentation seems to be an ideal surface where to open entry points and backdoors in the practice of software development. A crossroads where different knowledges meet in the making of software: beginners moving their first steps into coding, as well as experienced programmers looking for reference on a particular function. A space where to acknowledge the massive labor of care involved in coding culture besides technicalities, otherwise often marginalized. A place where to welcome different voices: not just engineers, not just experts, not just dudes. A way to broaden participation.
Code documentation is an interface between the code, the user, the developer, and the world. Living close to the source code, but at the same time being less rigid and more expressive, documentation seems to be an ideal surface where to open entry points and backdoors in the practice of software development. A crossroads where different knowledges meet in the making of software: beginners moving their first steps into coding, as well as experienced programmers looking for reference on a particular function. A space where to acknowledge the massive labor of care involved in coding culture besides technicalities, otherwise often marginalized. A place where to welcome different voices: not just engineers, not just experts, not just dudes. A way to broaden participation.
coding contingencies means coding is always coding within context
programming as a way to share context
documentation to inject context into code to address issues
and create different entry points
politics of participation
economies of care
politics of representation
aesthetic practices and worlding
### Coding Contingencies
### Coding Contingencies
@ -25,11 +15,7 @@ It's an approach that helps us to think about software as a cultural object. Som
An object that, in turn, can be used to probe its surroundings. Who is developing? Who is going to use it? Who is paying for it and why? How is it structured? It is a big and centralized system or a loose collection of small and interchangeable tools? How long is it supposed to last? How can be fixed if it breaks?
An object that, in turn, can be used to probe its surroundings. Who is developing? Who is going to use it? Who is paying for it and why? How is it structured? It is a big and centralized system or a loose collection of small and interchangeable tools? How long is it supposed to last? How can be fixed if it breaks?
The main focus of this chapter is to explore software documentation as a surface where these kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source.
The main focus of this chapter is to explore software documentation as a surface where these kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. A way to situate programming in specific contexts, but also to inject our contexts into programming practices. Hence the idea of code documentation as a backdoor: a passage to infiltrate software culture, to change things from the inside and create more entry points.
A way to situate programming in specific contexts.
!!! note "backdoor here"
### Documentation & distribution
### Documentation & distribution
@ -48,14 +34,13 @@ One example is the paradigm of constant availability of the server. Behind every
### Distributed autorship
### 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.
_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"
!!! 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`
An endpoint is a location where the API receives requests for specific resources, usually in the form of 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.
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.
@ -77,9 +62,9 @@ As argumented by Kit Kuksenok during the activation of their workshop _Sharing P
_360 degrees of proximities_ is a project emerging from a network of feminist servers, addressing the problem of invisible labor tipically associated with maintainance of digital infrastructure.
_360 degrees of proximities_ is a project emerging from a network of feminist servers, addressing the problem of invisible labor tipically associated with maintainance of digital infrastructure.
After a sucessfull setup of a self-hosted Peertube instance, a federated platform for sharing video contents, the group started questioning aspects regarding the maintenance of the system. Instead of centralizing the service in a self-exploitative scenario, they decided to redistribute it on the network working together with other feminist and queer communities, empowering them to build their own video platforms autonomously, but in a joint effort. Here 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.
After a sucessfull setup of a self-hosted Peertube instance, a federated platform for sharing video contents, the group started questioning aspects regarding the maintenance of the system. Instead of centralizing the service in a self-exploitative scenario, they decided to redistribute responsabilities on the network, working together with other feminist and queer communities, empowering them to build their own video platforms autonomously, but in a joint effort. Here 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.
Here is where the interesting friction of situated documentation arises: how to share knowledge about something deeply situated with other contexts? How to remain legible and accessible, while at the same time preserving specific and characterstic choices? Usually documentation doesn't take into account the messiness of coding contingencies, where multiple software cohexist in the same server and configurations conflict with each other, or are installed with different setups. Collective learning moments can close the gap between an ideal setup described in the docs and a real-world, situated one.
Here is where the interesting friction of situated documentation arises: how to share knowledge about programming practices deeply situated with other contexts? How to remain legible and accessible, while at the same time preserving specific and characteristic choices? Usually documentation doesn't take into account the messiness of coding contingencies, where multiple software cohexist in the same server and configurations conflict with each other, or are installed with different setups. Collective learning moments can close the gap between standard setup described in the docs and a real-world, situated one.
### Representation specs
### Representation specs
@ -114,12 +99,9 @@ _Code for the project pages on the soupboat. The figure with the header is added
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.
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.
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.
!!! note "better conclusion"
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.
wrap up why documentation here is better than implementation
### Hello worlding
### Hello worlding
@ -161,17 +143,13 @@ 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.
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 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.
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.
In the essay, they highlight how poetry often does offer rich context and a world for a work to live in, while _software documentation_ often does not. A poetic practice of world-building would benefit _code documentation_, allowing for multiple potential narratives to sprawl out nonlinearly, validating them, inviting to question the surroundings of the code, and offering points of resistance to the smooth flow of capital, which relies on a singular, totalizing interpretation of the world. Hence the idea of chimeric worlding: to provincialize _code documentation_ with multiple ways of structuring knowledge, leaving open ended spaces for others to participate.
In the essay, they highlight how poetry often does offer rich context and a world for a work to live in, while _software documentation_ often does not. A poetic practice of world-building would benefit _code documentation_, allowing for multiple potential narratives to sprawl out nonlinearly, validating them, inviting to question the surroundings of the code, and offering points of resistance to the smooth flow of capital, which relies on a singular, totalizing interpretation of the world. Hence the idea of chimeric worlding: to provincialize _code documentation_ with multiple ways of structuring knowledge, leaving open ended spaces for others to participate.
In the Screenless Office, the bureau aesthetic, with its collective imagery of characters, situations, and power dynamics, becomes a personal interaction design framework. Here the system is structured enough to articulate a complex application in a coherent, clear and legible way. And yet, the cosmology of the office remains open to contribuitions coming from elsewhere, say, another departement such as the `Canteen of the Screenless Office` inaugurated during a workshop with Howell at XPUB, with all its peculiar set of characters, aesthetics and documentation practices.
In the Screenless Office, the bureau aesthetic, with its collective imagery of characters, situations, and power dynamics, becomes a personal interaction design framework. Here the system is structured enough to articulate a complex application in a coherent, clear and legible way. And yet, the cosmology of the office remains open to contribuitions coming from elsewhere, say, another departement such as the `Canteen of the Screenless Office` inaugurated during a workshop with Howell at XPUB, with our own peculiar set of characters, aesthetics and documentation practices.
!!! placeholder "si16 api docstrings"
Our first project in XPUB was Special Issue 16: a collective exploration of natural language processing with a vernacular turn. It was published as an API, offering several functions to users to play with strings and texts.
