- Ullman, E. (2017). _Life in code : a personal history of technology._ New York: Mcd, Farrar, Straus And Giroux.
- Bridle, J. (2016). _welcome.js. GitHub._ [online] Available at: https://github.com/stml/welcomejs
- Bridle, J. (2016). _welcome.js | booktwo.org._ [online] Available at: http://booktwo.org/notebook/welcome-js/
- Donald Ervin Knuth (1992). _Literate programming._ Stanford, Calif.: Center For The Study Of Language And Information.
- Ehmke, C. A. (2018). _The Post-Meritocracy Manifesto_ [online] Available at: https://postmeritocracy.org/
- Fisher, M. (2013). _Suffering With a Smile._ [online] Available at: https://theoccupiedtimes.org/?p=11586
- Fuller, M., ed. (2008). _Software studies a lexicon._ Cambridge, Massachusetts Mit Press.
- Gabriel, R.P. (1998). _Patterns of Software._ Oxford University Press, USA.
- GNU (n.d.). _GNU gettext utilities._ [online] Available at: https://www.gnu.org/software/gettext/manual/gettext.html.
- Howell, B. (2016). _The Screenless Office._ [online] Available at: http://screenl.es/
- Howell, B. (2016). _the-screenless-office GitLab._ [online] Available at: https://gitlab.com/bhowell/the-screenless-office
- Karagianni, M. (2022). _Read The Feminist Manual._ Athens, Greece: Psaroskala Zines.
- Karagianni, M. et al (2023). _Feminists Federating._ Toward a Minor Tech - A peer reviewed Newspaper vol 12
- Hanlon, J. (2018). _Stack Overflow Isn’t Very Welcoming. It’s Time for That to Change._ [online] Stack Overflow Blog. Available at: https://stackoverflow.blog/2018/04/26/stack-overflow-isnt-very-welcoming-its-time-for-that-to-change/.
- Heaton, R. (2019). _Programming Projects for Advanced Beginners #6: User Logins._ [online] Available at: https://robertheaton.com/2019/08/12/programming-projects-for-advanced-beginners-user-logins/
- Marino, M.C. (2020). _Critical code studies._ Editorial: Cambridge, Massachusetts: The Mit Press.
- Soon, W. and Geoff Cox (2020). Aesthetic programming : a handbook of software studies. London: Open Humanities Press.
- Fuller, M., ed. (2008). Software studies a lexicon. Cambridge, Massachusetts Mit Press.
- Gabriel, R.P. (1998). Patterns of Software. Oxford University Press, USA.
- A Wishlist for Trans\*femminist Servers. 2022. https://etherpad.mur.at/p/tfs
- Hanlon, J. (2018). Stack Overflow Isn’t Very Welcoming. It’s Time for That to Change. [online] Stack Overflow Blog. Available at: https://stackoverflow.blog/2018/04/26/stack-overflow-isnt-very-welcoming-its-time-for-that-to-change/.
- Fisher, M. (2013). Suffering With a Smile. [online] Available at: https://theoccupiedtimes.org/?p=11586 [Accessed 16 Feb. 2023].
- Norman Wilson, A. (2011). Workers Leaving the Googleplex. [online] Available at: http://www.andrewnormanwilson.com/WorkersGoogleplex.html
- GitHub. (2021). require `describe()` function in p5 sketches? · Issue #5427 · processing/p5.js. [online] Available at: https://github.com/processing/p5.js/issues/5427 [Accessed 10 Apr. 2023].
- Karagianni, M. et al (2023). Feminists Federating. Toward a Minor Tech - A peer reviewed Newspaper vol 12
- Donald Ervin Knuth (1992). Literate programming. Stanford, Calif.: Center For The Study Of Language And Information.
- Special Issue 16 (2022). Learning How to Walk while Catwalking. [online] Available at: https://issue.xpub.nl/16/ [Accessed 12 Apr. 2023].
- Meta Stack Exchange. (2009). _Should ‘Hi’, ‘thanks’, taglines, and salutations be removed from posts?_ [online] Available at: https://meta.stackexchange.com/a/93989
- nand2tetris. (2017). _nand2tetris._ [online] Available at: https://www.nand2tetris.org/.
- Norman Wilson, A. (2011). _Workers Leaving the Googleplex._ [online] Available at: http://www.andrewnormanwilson.com/WorkersGoogleplex.html
- p5js.org. (2019). _p5.js._ [online] Available at: https://p5js.org/.
- p5js.org. (2015). _Debugging | p5.js._ [online] Available at: https://p5js.org/learn/debugging.html
- processing/p5.js (2021). _require describe() function in p5 sketches? · Issue #5427 · processing/p5.js._ [online] Available at: https://github.com/processing/p5.js/issues/5427 [Accessed 10 Apr. 2023].
- Procida, D. (2017). _Diátaxis._ [online] Available at: https://diataxis.fr/.
- Queer Service team (2021). _Queer Motto API · GitLab._ [online] Available at: https://gitlab.com/siusoon/queer-motto-api
- 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.
- 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.
- 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
https://p5js.org/learn/debugging.html
1. Code documentation flows, with a roster and a barn owl.
2. Linux Kernel Map. source: [makelinux.github.io/kernel/map](https://makelinux.github.io/kernel/map/)
3. Detail of Linux Kernel mapped into the [four stages of simulation meme template](https://knowyourmeme.com/photos/2445322-four-stages-of-simulation)
4. The wolf, goat and cabbage problem applied to coding.
5. A provocative post with slightly austrian accent on Mastodon. Thanks Naami for the screenshot.
6. Message in console printed by Facebook to stop users. source: [booktwo.org](https://booktwo.org)
7. Message in console printed by Bridle to welcome users. source: [booktwo.org](https://booktwo.org)
8. Frustrated developer apparently busy with technical writing. Thanks Cristina for the screenshot.
9. Diagram of a Vue instance lifecycle, illustrating the different entry points of the template design pattern. source: [vuejs.org](https://vuejs.org/guide/essentials/lifecycle.html)
10. Lifecycle and ecosystem of Padliography: a wiki-powered link bookmarking system.
11. Diagram of the Diataxis framework. Rework of the original one found at [diataxis.fr](https://diataxis.fr/)
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/)
18. Documentation generated from the Notebook files for the Repeat function. source: [issue.xpub.nl/16](https://issue.xpub.nl/16/)
`Flow #1`
Documentation broadens participation in the making of software: lowering barriers and offering entry points for people to understand and attune with code.
@ -6,11 +7,11 @@ Documentation that assumes a certain type of reader can result inaccessible. The
Whenever too much technical proficiency is required to even read the documentation, knowledge becomes inaccesible, and confined in the ivory tower. Not filtering information becomes a filter to who can engage with it, a backfiring practice that reinforces the segmentation between who is allowed in and who is not: only the already knowledgeable ones can access, while others are kept out. Contents need to be curated, that does not mean oversimplified or generalised, but rather made legible.
Cultivating legibility is not an easy task, especially when it comes to computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narratives and intertwined plots and main characters at the same time. The purpose of an abstraction is to function as a symbol, as a mentally manoeuvrable concept, free from the details of its technical implementation. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up the digital stack.
Cultivating legibility is not an easy task, especially when it comes to computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narratives and intertwined plots and main characters at the same time. The purpose of an abstraction is to function as a symbol, as a mentally manoeuvrable concept, free from the details of its technical implementation. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up the digital stack.
Take a course such as the one presented by Noam Nisan and Shimon Schocken in _From NAND to Tetris_, where they slowly build a programmable computer capable of running the classic game, starting from simple NAND logic gates, in other words, from microchips and electronics. Layer after layer, from boolean operations with 0 and 1 to registers and CPUs, from machine language to high level programming. Here one can try to unwind the coil and start understanding programming from scratch, but this approach is best suited to a university curriculum, and it's often not very effective when facing real-world problems, with real-world constraints, and real-world circumstances.
@ -22,7 +23,7 @@ The series _Programming Projects for Advanced Beginners_ by Robert Heaton embrac
A lesson can be learned: sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about all of these at once. Programming is about balancing these different aspects depending on the situation. Keeping this balance in mind when writing code documentation gives to the writer room to adjust the tone, intensity and approach depending on who will be reading these docs.
### Programming language
@ -57,7 +58,7 @@ Toxic geek masculinity reinforces stereotypes such as gendered roles in programm
Writing documentation is demanding. It's more delicate than programming, and requires a whole set of skills not usually treasured by the dev community. A kind of emotional intelligence and sensitivity that is far to be found in the competitive and pragmatic wastelands of the IT industry. Nobody here wants to write documentation, or pay anyone 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.
@ -87,9 +88,9 @@ When you open the browser inspector on the Facebook website, you are confronted
`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 into 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 that allows users to see the underlying code of the website they are visiting. From here it provides some guidance for newcomers to access, inspect and modify the source code of web pages. A process that opens doors and lets people in, giving them more agency by demistifying technology.
Whether in a large project or a small gesture, attention to language can be transformative. In code documentation it can help deconstruct the false dichotomy between programmer and user, or pro and _newbie_. It can create spaces that feel safer, where people are invited to participate, express themselves and contribute to the community. It can help undo the impostor syndrome that affects many programmers, and that feeds on some hidden and inaccessible fundational knowledge that is nowhere to be found in code documentation. It can help shed some light on the massive amount of work that goes into the making of software: recognising all contributions, not just those of engineers.
@ -101,7 +102,7 @@ There's a multitude of ways in which changes to the codebase affect the document
In addition to the technical aspects, the editorial work needs to be taken into account. Adjustments and corrections and line-editing, clarifications of convoluted paragraphs, rephrasing of confused sentences, highlighting of important passages. Some projects support internationalization, and the contents are translated and adapted to different languages' structures.
Documentation can be as simple as a plain text file placed near the code. A `README.txt` that invites developers to take a look before diving into the program. However, as projects become larger and more articulated, the need for more comprehensive and structured formats arises. Printed technical manuals have today transformed and spreaded into many different shapes. Wikis and websites generated with various tools, each with particular focus and features.
@ -125,9 +126,9 @@ 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, uses a diagram to explain the lifecycle of its components: when data is received from the server, when an element is rendered on screen, and when it disappears. What at first feels like magic, gradually becomes clearer. To present a structure means also to offer a way of reasoning about it. The reader gains a certain understanding and agency over the tools they are about to use.
Code documentation is not just pure introspection. Consider the diagram created for the _Padliography_, a bookmarking system for collecting links of otherwise scattered _Etherpad_ documents. It not only describes what's going on in the code, but also taps into its surroundings: the _Soupboat_ server and the _XPUB and Lens Based wiki_.
@ -143,7 +144,7 @@ The devil is in the details, and software as well: the translation between human
Documentation is not just for beginners: it's a code companion. You never stop reading it. Even experienced programmers must consult the docs when first encountering a software, and return to it when they need a refresher on the syntax of a particular command. They are continuously looking at code from multiple distances: close to the source code through lines of comment, or from printed books, along with pages of explanations and use cases.
This tentacular surface can reach a programmer at different moments of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the variety of forms that documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring diagrams and drawings. Daniele Procida proposes a systematic approach to organise this wealth of formats (2017). His framework focuses on the needs of different types of readers: by leveraging between practical steps and theoretical knowledge, he charts four main modes of technical writing. Each format has its own approach and intentions, and answers different questions.
@ -26,13 +26,13 @@ A way to open up to plurality, to questioning, to instability, to consent, to si
These principles are reflected in the documentation of the Queer Motto API, a _software as a service_ commissioned by transmediale in 2020-2021 and developed by the Queer Service team (Winnie Soon, Helen V. Pritchard, Cristina Cochior, and Nynne Lucca). The project challenges the idea of software as a smooth, always-on service, with a motto generator that sometimes refuses to work, takes a nap when it needs to REST, or goes on strike to celebrate important days like the 8th March.
!!! note ""
In their documentation _REST_ is used as a word play with the acronym _representational state transfer_, typical of API development.
In their documentation _REST_ is used as a word play with the acronym _representational state transfer_, typical design pattern of API development.
The Queer Motto API is published in the form of an Application Programming Interface (API), an online service that other developers can request from their applications to use generated feminist motto. By being released as an API, the service is inherently linked with other projects, such as the Transmediale website, that uses it to display a new motto every day. Who wants to use the API has to agree to the terms and conditions, which are detailed in the documentation available in the project repository. The _readme_ offers an understanding of the various technical moments and aspects involved in interacting with a typical software-as-a-service, but narrates them from a feminist perspective. Error codes, service availability, consent and refusal, request and response, token policy, and all the terms neutralised by the normativity of everyday tech, are reactivated here as powerful narrative (and subversive) devices.
One example is the paradigm of the constant availability of the server. Behind every _SaaS_ there are always a server: the so-called _someone else's computer_ working behind the scenes. The seamless cloud picture of big tech rarely includes these machines, which are abstracted and hidden from the user. Instead, in the Queer Motto API, the presence of the server is a key aspect, especially when it decides to take a nap or refuses to work because it is on strike. These behaviors are documented with various error codes, giving developers using the API a way to make their applications react accordingly, and even join the cause.
@ -43,7 +43,7 @@ a workbook dedicated to the alternative text descriptions that make web images a
Websites are made of HTML, a markup language based on 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.">
@ -68,7 +68,7 @@ However, an implementation-first approach is not always an option, and code docu
In the discussions surrounding the development of this open source project, contributors began to consider how to encourage the use of this feature. From an initial suggestion to make it a requirement 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.
### Situated docs
@ -122,7 +122,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,23 +142,23 @@ 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.
# wrapping up what did we learn
<!--# wrapping up what did we learn-->
!!! placeholder "[ fade out towards outro ]"
outro could be introduction of project
and mention _care for code_ and doc sessions
as a way to create entry points and pathways to read through this wealth of practices
<!--!!! placeholder "[ fade out towards outro ]"-->
<!-- outro could be introduction of project-->
<!-- and mention _care for code_ and doc sessions -->
<!-- as a way to create entry points and pathways to read through this wealth of practices-->
Code documentation as a backdoor because it can reach many different kinds of programmers, and in many different ways.
It works at different scales, from big projects to small gestures.
<!-- Code documentation as a backdoor because it can reach many different kinds of programmers, and in many different ways.-->
<!-- It works at different scales, from big projects to small gestures.-->
_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: atm 7581 but writing conclusions and intro
km0