diff --git a/bibliography.md b/bibliography.md index 6473110..b00c059 100644 --- a/bibliography.md +++ b/bibliography.md @@ -1,17 +1,56 @@ ## Bibliography -- 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. +- 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 -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/) diff --git a/chapters/00_intro.md b/chapters/00_intro.md index 210a6db..13f90f5 100644 --- a/chapters/00_intro.md +++ b/chapters/00_intro.md @@ -1,13 +1,8 @@ ## 0. Intro -!!! note "example intro" - one does this and needs documentation - one does that and has to read the docs - whatever returns to the docs - There are two flows around code documentation: -![A square in center. A roster enter from the front with a plain arrow. A barn owl enter from the back, with a dashed arrow. ](../img/backdoor.jpg "Two flows around code documentation: entry points and backdoors.") +![A square in center. A roster enter from the front with a plain arrow. A barn owl enter from the back, with a dashed arrow. ](../img/backdoor.jpg "1. Two flows around code documentation: entry points and backdoors.") `Flow #1` Documentation broadens participation in the making of software: lowering barriers and offering entry points for people to understand and attune with code. diff --git a/chapters/01_entry_points.md b/chapters/01_entry_points.md index 33c1657..a0d6206 100644 --- a/chapters/01_entry_points.md +++ b/chapters/01_entry_points.md @@ -1,3 +1,4 @@ + ## 1. Entry points ### "Natural" reader @@ -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. -![Structured in six columns: system, processing, memory, storage, networking, human interface. Organized with seven depth: from user space interfaces down to virtual, bridges, functional, devices control, hardware interfaces, electronics.](../img/kernel.png "Linux kernel map. From the bottom up, every horizontal layer is a level of abstraction that build on the previous one.") +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. -![Detail of human interface functions column of the Linux kernel, cut out onto the meme format of four stages of simulation.](../img/sim.jpg "Detail of Human Interface Functions mapped onto the four stages of simulation meme template.") +![Structured in six columns: system, processing, memory, storage, networking, human interface. Organized with seven depth: from user space interfaces down to virtual, bridges, functional, devices control, hardware interfaces, electronics.](../img/kernel.png "2. Linux kernel map. From the bottom up, every horizontal layer is a level of abstraction that build on the previous one.") -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. +![Detail of human interface functions column of the Linux kernel, cut out onto the meme format of four stages of simulation.](../img/sim.jpg "3. Detail of Human Interface Functions mapped onto the four stages of simulation meme template.") 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. -![A skiff with a label saying coding, a wolf saying accessibility, goat saying flexibility, cabbage saying performance](../img/wolf_goat_cabbage.jpg "The wolf, goat and cabbage problem applied to coding.") +![A skiff with a label saying coding, a wolf saying accessibility, goat saying flexibility, cabbage saying performance](../img/wolf_goat_cabbage.jpg "4. The wolf, goat and cabbage problem applied to coding.") ### 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. -![Post on mastodon by user josef boosted by user Pry Mincer saying with slightly austrian accent: so many things nowadays don't have documentation, they just point you at a discord server. this is because nobody makes or does anything anymore, they just chat on the internet with eachother. in 10 years there wont actually even be software anymore, just discord groups where people can chat about what software might be like if it existed](../img/discord.jpg "A provocative post with slightly austrian accent in Mastodon") +![Post on mastodon by user josef boosted by user Pry Mincer saying with slightly austrian accent: so many things nowadays don't have documentation, they just point you at a discord server. this is because nobody makes or does anything anymore, they just chat on the internet with eachother. in 10 years there wont actually even be software anymore, just discord groups where people can chat about what software might be like if it existed](../img/discord.jpg "5. A provocative post with slightly austrian accent on Mastodon") 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. @@ -125,7 +126,7 @@ 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. -![A flowchart with different stages of the Vue component renders. ](../img/vue-lifecycle.png "Introspective diagram of a Vue instance lifecycle, illustrating the different entry points of the template design pattern.") +![A flowchart with different stages of the Vue component renders. ](../img/vue-lifecycle.png "Diagram of a Vue instance lifecycle, illustrating the different entry points of the template design pattern.") ![A ironic diagram of the different stages of the padliography over the lifecycle of frogs](../img/pad-lifecycle.jpg "Lifecycle and ecosystem of Padliography: a wiki-powered link bookmarking system.") diff --git a/chapters/02_backdoors.md b/chapters/02_backdoors.md index 4883184..2edcf57 100644 --- a/chapters/02_backdoors.md +++ b/chapters/02_backdoors.md @@ -26,7 +26,7 @@ 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. @@ -142,7 +142,7 @@ 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 "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 "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 "Documentation generated from the Notebook files for the Repeat function") @@ -152,13 +152,13 @@ The title of the project was a declaration of intents: when approaching the tech -# 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 + + + + - 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. + + diff --git a/chapters/03_outro.md b/chapters/03_outro.md new file mode 100644 index 0000000..898b7a5 --- /dev/null +++ b/chapters/03_outro.md @@ -0,0 +1,16 @@ +## 3. Outro + +- documentation as a rich set of practices + +- coming with many different formats + +- meeting developers in different moments of their lives + +- two ways to think about it: + +- entry point to broadens participation + + + + +- a backdoor to inject context and values into making of software diff --git a/cover.md b/cover.md new file mode 100644 index 0000000..93d463d --- /dev/null +++ b/cover.md @@ -0,0 +1,10 @@ +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: atm 7581 but writing conclusions and intro diff --git a/notes.md b/notes.md index 864969b..0e4d782 100644 --- a/notes.md +++ b/notes.md @@ -12,7 +12,7 @@ [ ] hello worlding: code documentation as an entry point / backdoor to programming practices [ ] cover & word count -[ ] grammar +[x] grammar [ ] abbraviation check [ ] toc [ ] vue image is too big consider adjusting