diff --git a/chapters/01_who_is_reading.md b/chapters/01_who_is_reading.md index be4f598..6e75ce7 100644 --- a/chapters/01_who_is_reading.md +++ b/chapters/01_who_is_reading.md @@ -1,18 +1,18 @@ -# Who is reading +## Who is reading -``` +` documentation as a publishing surface? yes because - it's often first thing one reads when approaching software - see getting started + it's often first thing one reads when approaching software - see getting started it's consulted not just from beginner, but also experienced users - see a code companion yes but it should be less hostile - see welcoming writing it should stop assuming reader - see natural readers -``` +` -## Getting started +### Getting started `("Getting startled" could also make for a nice title)` Reading undocumented code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective. It is often the first thing one gets across when approaching a new library or programming language, and it shapes the way a developer thinks about particular piece of code. @@ -51,9 +51,9 @@ Writing documentation is demanding. It's more delicate than programming, and req 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 on any problem in no time. -But it's not rare for these places to feel unwelcoming, or even hostile. In 2018, Stack Overflow publicly admitted that there was a problem concerning their userbase. The space felt unfriendly for _outsiders_, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018). +But it's not rare for these places to feel unwelcoming, or even hostile. In 2018, Stack Overflow publicly admitted that there was a problem concerning their userbase. The space felt unfriendly for _outsiders_, such as newer coders, women, people of color, and others in marginalized groups (Hanlon, 2018). -For years there have been discussions on the platform about tone. At the question _"Should 'Hi', 'thanks', taglines, and salutations be removed from posts?"_, one of the founders of Stack replied with a [RegEx](https://meta.stackexchange.com/a/93989) to filter _automagically_ what some of the experienced users perceived as noise. This _regular expression_, a way to target specific text patterns in programming, started then to be silently applied to every query sent to the website, trimming out etiquette and leaving just technicalities. +For years there have been discussions on the platform about tone. At the question _"Should 'Hi', 'thanks', taglines, and salutations be removed from posts?"_, one of the founders of Stack replied with a [RegEx](https://meta.stackexchange.com/a/93989) to filter _automagically_ what some of the experienced users perceived as noise. This _regular expression_, a way to target specific text patterns in programming, started then to be silently applied to every query sent to the website, trimming out etiquette and leaving just technicalities. Far from being just an isolated problem, this crudity is deeply embedded in the IT discourse, soaking through technical writings as well. The denigrating expressions of superiority in matters concerning programming that Marino calls _encoded chauvinism_ (Marino, 2020) constitute the main ingredient in the brew of toxic geek masculinity. _Real programmers_ don't use this code editor. _Real programmers_ don't use this programming language. _Real programmers_ don't care about others feelings. Etc. @@ -62,7 +62,7 @@ Ellen Ullman accounts on the emotional dumbness of her _real programmers_ collea Programming means to deal with picky stubborn machines that don't overlook a single typo. It requires a high tolerance for failure. It is frustrating. But to project this frustration onto other users, as in the `Read The Fucking Manual` response to a request for help, it's a form of negative solidarity (Fisher, 2013) that poses serious barriers to the participation in the making of software. -Instead... +Instead... - lowering barriers - debugging (p5.js education working group, 2015) @@ -76,8 +76,8 @@ Instead... - programming for the millions (ullman, 2016) - read the feminist manual (karagianni, 2021 ) -- bro culture ? ? ? - (could be the transition from previous section) +- bro culture ? ? ? + (could be the transition from previous section) (could be the example with evvvvil help patches) vvvv is a visual programming language that offers an agile approach to prototyping, adoperated especially in the context of interaction design. It's focused on rapid and iterative work of fine tuning, necessary when dealing with real time inputs, such as sensors, live data, or human interaction. @@ -85,7 +85,7 @@ vvvv is a visual programming language that offers an agile approach to prototypi vvvv is a visual programming language used esp with interaction design fine tuning, iterative process -help patches +help patches - refer to a specific cultural niche ? see ullman, even tho need to counter balance with other examples diff --git a/chapters/03_hello_worlding.md b/chapters/03_hello_worlding.md index 1bce75b..14700f9 100644 --- a/chapters/03_hello_worlding.md +++ b/chapters/03_hello_worlding.md @@ -4,7 +4,7 @@ The third section is focused on worlding, and the relation between code, documen Here documentation is seen as a surface that could host principles in close contact with algorithms, letting them entangle and shape each other. A way to orientate our instruments towards "non-extractive relationships, but in the meantime, being accountable for the ones they are complicit with." (A Wishlist for Trans\*feminist Servers, 2022) -__Sections:__ +__Sections:__ A structure on how to organize the examples and case studies proposed. @@ -12,49 +12,49 @@ A part of theoretical examples of technology and worlding: Trans\*feminist Serve A part of case studies. The soupboat. Avantwhatever.net. Queer Motto API. The Screenless Office. The uxn ecosystem. `list wip` -## Going with the flows +### Going with the flows -There could be several approaches for making worlds around software. Here are some keywords that refer to the kind of flow these worlding techniques activate.Drafted here are three directions: to _reclaim_ is to get something back: something that was stolen, or taken away, or lost, or forgotten. To _reenchant_ means to intercept and reorientate towards different directions. To readjust a process, or to move for a different purpose. To _reassure_ serves as prompt to keep going. It helps making meaning together, and refresh ideas. It offers way to register choices, keep track and share what has been done so far. +There could be several approaches for making worlds around software. Here are some keywords that refer to the kind of flow these worlding techniques activate.Drafted here are three directions: to _reclaim_ is to get something back: something that was stolen, or taken away, or lost, or forgotten. To _reenchant_ means to intercept and reorientate towards different directions. To readjust a process, or to move for a different purpose. To _reassure_ serves as prompt to keep going. It helps making meaning together, and refresh ideas. It offers way to register choices, keep track and share what has been done so far. These labels are open and loose, overlapping and not mutually exclusive, temporary and on the move. They are meant to change, to expire fast, and going bad even faster: they require continuous treatments and repeated efforts. That's why I'm naming them all after the _re_ prefix: to aknowledge their being in progress, second hand again, already contaminated. Borrowed by friends and foes, that had borrowed themselves from someone else. One should diffidate of these categories because they're instable. Nonetheless, they offer ways to visualize different strategies to create worlds around software. -``` +` reclaim take back reenchant intercept -reassure keep going +reassure keep going reclaim renegotiate, recuperate, remember, refuse, reactivate reenchant redirect, rebirth, reboot, rebrand, redeem reassure refrain, refresh, regret, reaffirm, register, readme -``` +` -## reclaim +### reclaim There seems to be a risk in reducing sociality around software to a conflict between "friends and foes": a risk to reproduce forms of exclusion and violence typical of the IT world. To just swap good and bad, and offer clean solutions. Try instead to apply Chantal Mouffle's concept of agonistic politics to software development intended as struggle between different hegemonic projects. How can documentation create new spaces around code? Where new spaces means spaces for who are excluded. -Think about the works around queerying technologies, from Zach Blass to Trans\*feminist servers, to Queerying UNIX, to 360 degrees of proximity, the Queer motto API. +Think about the works around queerying technologies, from Zach Blass to Trans\*feminist servers, to Queerying UNIX, to 360 degrees of proximity, the Queer motto API. Think about projects related to accessibility, and space built by and for people with diverse ability. Alt-text poetry could be a good starting point. Think about the efforts to create safe spaces to learn. -## reenchant +### reenchant Reenchanting code cannot be just a process of rebranding. Cannot be just a matter of changing the visual identity of the documentation, or washing it green or pink or black, or to capitalize on the inclusion of minorities. -Re-enchanting code means to create new narrations around software. As the artist James Bridle writes trying to untangle the complex social and environmental implications of digital computation: _"Technology is not mere tool making and tool use: it is the making of metaphors"._ (James Bridle, 2018) These metaphors, like code documentation, influence the way we think and use our tools. +Re-enchanting code means to create new narrations around software. As the artist James Bridle writes trying to untangle the complex social and environmental implications of digital computation: _"Technology is not mere tool making and tool use: it is the making of metaphors"._ (James Bridle, 2018) These metaphors, like code documentation, influence the way we think and use our tools. `Example:` Master-slave examples on version control software documentation. See [BitKeeper](https://github.com/bitkeeper-scm/bitkeeper/blob/master/doc/HOWTO. ask#L223) `Example:` The military term _deploy_ adopted by CI/CD systems such as the one on GitLab. -`Example:` The naming of group of servers as fleet on AWS documentation, a term referring to naval formation, often with military connotation. +`Example:` The naming of group of servers as fleet on AWS documentation, a term referring to naval formation, often with military connotation. -These metaphors orient code in the world. They reinforce, highlight and validate certain practices. A fleet implies centralized control, a swarm implies direct influences between participants, a federation implies certain degrees of independence, etc. +These metaphors orient code in the world. They reinforce, highlight and validate certain practices. A fleet implies centralized control, a swarm implies direct influences between participants, a federation implies certain degrees of independence, etc. -Nanni Moretti was slapping people in the face to remark the importance of words and their usage, but in order to re-enchant code through documentation just finding & replacing terms is but a first step. +Nanni Moretti was slapping people in the face to remark the importance of words and their usage, but in order to re-enchant code through documentation just finding & replacing terms is but a first step. -To re-enchant means to re-trace genealogies, to intercept and re-orient narratives and offer a redemption arc to those projects that were left behind. `need better transition` +To re-enchant means to re-trace genealogies, to intercept and re-orient narratives and offer a redemption arc to those projects that were left behind. `need better transition` A good example is the work of documentation around the Uxn ecosystem, a personal computing stack initiated by the 100 Rabbits collective. To meet their needs for a portable and lightweight infrastructure and reduce the energy consumption of their digital tools (they live on a wind & solar powered sailboat), while keep continuing developing games and software ... @@ -67,7 +67,7 @@ The same with DuskOS, a small operative system that return to Forth --- -Three sources that could be explored here relate to an alternative to the model of technosolutionism. +Three sources that could be explored here relate to an alternative to the model of technosolutionism. Staying low @@ -79,4 +79,4 @@ Staying low -## reassure +### reassure