care for code materials

master
km0 1 year ago
parent b3b0492d54
commit 9dea8c59ec

@ -10,4 +10,56 @@ Writing documentation is tricky! But let's face this together: prompts and sugge
---
These sessions grow out of the contradiction of being frustrated in having to deal with undocumented pieces of software, and at the same time never documenting anything. While for sure there is some thrill in understanding how to stitch codes together, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
At the same time, this very lack of documentation could be used as a starting point.
Documentation is a space that interfaces between the code, the user, the developer, and the world. A space with potential to renegotiate and reclaim given margins and entry points. A chance to overwrite what is normalized, and let more voices participate in the discourse that is software.
Documentation is a way to produce narrations around software. To create a world for the code to inhabit, to stretch what is possible to do or to think with it. Documentation is a space for the political in the software. A surface that could host ideas in close contact with code, letting them entangle and shape each other.
## Ok ok ok ok but where to start?
One can start documenting code in many different ways. Every piece of software and every situation require something slightly different, so it's not that there's a right or wrong way to do it.
Here some prompts!
Feel free to add more `??? note that this could be an open repo`
### Start from the readers!
For who are you writing this documentation for?
Keep in mind that there are many different kinds of reader! Beginners and experienced programmers alike. Friends and strangers. Future selves.
Everyone reading the same documentation, but from a different point of view!
When writing there's no need to take into account every possible programmer on earth: a piece of documentation does not need to satisfy everyone!
see diataxis
### Start from the code!
A good way to start is commenting directly in the source code.
There are many constraints here: there is no formatting, there is limited space, there is no way to insert images, etc. These limitations however offer a good chance to focus and explain what the code is doing in the clearest way possible.
Code and comments have their own pace, flow and logic. One does not read code as they would read a traditional text! It's rare for a script to run in a linear fashion, from top to bottom: more often it jumps here and there, calling functions and methods scattered around the codebase.
Guide your reader!
There are many possible ways: order the comments progressively, rearrange the functions to follow a more sequential development, organize the code into blocks, link to external references, etc.
### Start from an image!
Reading source 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.
Sometimes an image is worth a thousand words. To illustrate the different steps of the process, or to give an overview of the program's lifecycle.
Flowcharts and Nassi-Schneiderman charts are traditional options in technical writing, but things don't have to be so strict and dry. Let your visual intelligence work for you.
![chae api]()
Explanation of an API by Chaeyoung Kim
![frogs]()
Lifecycle of an etherpad document when stored in the Padliography.
### Start with someone else!

@ -127,10 +127,10 @@ After the work in the past Special Issues, I'm trying to shift from compulsive d
## Relation to a larger context
Software comes from a really specific occidental cultural tradition.
Software tends to priviledge masculine, binary, exploitative and extractive practices.
Software is shrouded in technical obscurity.
Software comes invisible, transparent, neutral.
Software comes from a really specific occidental cultural tradition.
Software tends to priviledge masculine, binary, exploitative and extractive practices.
Software is shrouded in technical obscurity.
Software comes invisible, transparent, neutral.
Software models the world in order to control it.
To make software means not only to write code, but also to take a stance regarding this trends.
@ -157,5 +157,3 @@ To make place for code turns to be a necessary act of care in the process of sha
- Procida, D. (2017). _Diátaxis Documentation Framework_. `[online]` diataxis.fr. Available at: [diataxis.fr](diataxis.fr) [Accessed 18 Nov. 2022].
- Shirky, C. (2004). _Shirky: Situated Software_. `[online]` Available at: [https://www.gwern.net/docs/technology/2004-03-30-shirky-situatedsoftware.html](https://www.gwern.net/docs/technology/2004-03-30-shirky-situatedsoftware.html) [Accessed 11 Oct. 2022].
- Ullman, E. (2013). Close to the machine: Technophilia and its Discontents. London: Pushkin Press

@ -0,0 +1,61 @@
---
categories:
- Midwives
- Post
cover: letter.jpg
cover_alt: a letter that i receivved
date: 13/03/2023
description: Preparing some gift for co labourer
slug: postage-free-round-1
title: Postage Free round 1
---
Im grouped with Alex and Jian! It's a good match because Al is working a lot around facilitation, while Jian is actually writing a user manual for her project. Tre bien.
Now let's see brainstorm of what to put.
## Contents
### Quote from James Bridle - New Dark Age
Technology is not mere tool making and tool use: it is the making of metaphors. In making a tool, we instantiate a certain understanding of the world that, thus reified, is capable of achieving certain effects in that world. It thus becomes another moving part of our understanding of the world if, often, unconsciously. Thus we might say it is a hidden metaphor: a kind of transport or transference is achieved, but at the same time a kind of disassociation, an offloading of a particular thought or way of thinking into a tool, where it no longer needs thinking to activate. To think again or anew, we need to re-enchant our tools. The present account is merely the first part of such a re-enchantment, an attempt to rethink our tools not a repurposing or a redefinition, necessarily, but a thoughtfulness of them.
When one has a hammer, goes the saying, everything looks like a nail. But this is to not think the hammer. The hammer, properly conceived, has many uses. It may pull nails as well as drive them; it may forge iron, shape wood and stone, reveal fossils, and fix anchors for climbing ropes. It may pass sentence, call to order, or be thrown in a contest of athletic strength. Wielded by a god, it generates the weather. Thors hammer, Mjölnir, which created thunder and lightning when it was struck, also gave birth to hammer-shaped amulets intended to provide protection against the gods wrath or, through their resemblance to crosses, against enforced conversion. Prehistoric hammers and axes, turned up by the ploughs of later generations, were called thunderstones and were believed to have fallen from the sky during storms. These mysterious tools thus became magical objects: when their original purposes passed away, they were capable of taking on new symbolic meaning. We must re-enchant our hammers all our tools so they are less like the carpenters, and more like Thors. More like thunderstones.
### Quote from James Bridle - Ways of being
I would humbly propose three conditions for better, more ecological, machines: machines better suited to the world we want to live in and less inclined to the kinds of opacity, centralization of power and violence we have come to understand as the hallmarks of most contemporary technologies. These three conditions, I believe, are necessary for machines to become part of the flourishing communities of humans and non-humans weve sketched out in previous chapters. Our machines should be non-binary, decentralized and unknowing.
Lets start with non-binary. As we have seen, when we are capable of letting go of yes/no, either/or, zero/one questions whether in the turbulent flow of analogue computers, the open field of Facebook profiles, or the now tentatively explored operations of the o-machine we discover not merely new ways of doing and seeing things, more powerful than we ever imagined, but a richness and complexity to the world which surpasses imagination. This is the labyrinth of endlessly significant complexity, the deep, mysterious sumptuousness which Aldous Huxley wrote about, finally acknowledged by our conscious awareness and, potentially, our technology. The world itself is, plainly, non-binary. If we are to act ecologically through our tools, to act with care and justice towards one another and our more-than-human comrades, we must let go of binaries ourselves and free our machines to do likewise.
The non-binary quality of our desired machines also opens them up to a whole body of thought we havent so far considered, but that should be central to a rethinking of what computers could be: queer theory. Queer theory opposes the heteronormativity of culture in all its forms, including the gender binary. One of my favourite applications of queer theory to machines is the artist Zach Blass project, Queer Technologies, which includes a queer programming language called transCoder and a set of physical gender changers: computer cables which allow male cables to be transformed into female ones. By reimagining a technology designed for queer use, writes Blas, Queer Technologies critiques the heteronormative, capitalist, militarized underpinnings of technological architectures, design, and functionality. Crucially, by actually building the tools it imagines, it makes possible different ways of doing technology and thus of understanding the world that technology is part of.
As the genderqueer activist Jacob Tobia has pointed out, The first time that you heard the term binary, it was probably in a computer class. Heres the problem: People dont work like computers. Our identities, our thoughts, and our beliefs cant always be sorted easily into two categories. In the world we live in, we set up two distinct categories man and woman that everyone must choose between. But that doesnt actually reflect the full diversity of the human experience.33 As with the conscious decision to remove master/slave terminology from the lexicon of technology, to change the way we describe and build computers could have real repercussions, not only for their own architecture and capabilities, but for the lives of people whose experience is shaped by such technological metaphors which is to say, all of us.
The second condition, decentralization, draws from the lessons of the octopus and the slime mould to acknowledge the power of communal, cooperative undertaking. The power of communities and systems lies in their intra-action, their becoming-together to produce something greater than their parts. The process of decentralization follows the distribution of networks like the internet, but additionally insists that actual power, rather than mere connectivity, is shared out. We already have the means and know-how to do this, although its actual implementation has hitherto been relegated to the fringes of technological culture by the overbearing pressure of corporate monopolies and corporate profit-seeking.
The open-source movement is one such example of redistribution. This is the practice of publishing the full codebase every line of code which makes up a piece of software for public scrutiny and critique. By making the actual code of software and hardware accessible and legible to all, open-source practices decentralize knowledge and provide the basis for collective and self-education. The field of distributed computing is another example: it has given birth to both the extreme democracy of file-sharing and cryptocurrencies and to scientific initiatives like SETI@home and Folding@home. The former seeks to discover life in outer space, the latter to develop new cures to disease. Both use the power of remote processors provided by volunteers the computers of the general public, linked by the internet to churn through complex calculations which would overburden any single supercomputer. Its perhaps unsurprising that both these charismatic and successful examples of the form are concerned with life itself. Federated and peer-to-peer networks are a third example of decentralization. These are attempts to recreate the power and affordances of contemporary social networks, website hosts and even video calls, by allowing every user to build, host and control their own fragment of the wider network. In doing this, users actively reshape the network itself, transforming it from one centred around a few, privately owned hubs, to one in which users are directly connected to one another: a change in technology which results in a physical change to the topography and power relationships of the network itself.34
The project of decentralization also encompasses the process of decentring ourselves: the acknowledgement that humans are not the most important species on the planet, nor the hub around which everything else turns. Rather, we are a specialized but equal part of a vaster, more-than-human world, of no greater or lesser significance than any other part. Decentring is a complex task which requires us to think deeply about our relationships with the more-than-human world, and to understand our actions and the tools which we create as contributions to, and mediations with, everything else, instead of as unique, and uniquely powerful, artefacts of human superiority.
The third condition, unknowing, means acknowledging the limitations of what we can know at all, and treating with respect those aspects of the world which are beyond our ken, rather than seeking to ignore or erase them. To exist in a state of unknowing is not to give in to helplessness. Rather, it demands a kind of trust in ourselves and in the world to be able to function in a complex, ever-shifting landscape over which we do not, and cannot, have control. This is a basic imperative of being human in a more-than-human world and has always been acknowledged by traditional cosmologies, through their observance of ritual and their practical entreaties to the intercession of the non-human beings plants, animals, spirits and weather systems which enable our survival.
Many of our most advanced contemporary technologies are already tuned towards unknowing, none more so than machine-learning programmes, which are specifically designed for situations which are not accounted for in their existing experience. Applications such as self-driving cars, robotics, language translation, and even scientific research the generation of knowledge itself are all moving towards machine-learning approaches precisely because of this realization that the appropriate response to new stimuli and phenomena cannot be pre-programmed. Nonetheless, such programmes can all too easily continue to ignore or erase actual reality with devastating consequences if they perceive themselves in the same way that we, their creators, have always seen ourselves: as experts, authorities and masters. To be unknowing requires such systems to be in constant dialogue with the rest of the world, and to be prepared, as the best science has always been, to revise and rewrite themselves based on their errors.
An example of such an unknowing system is the Optometrist Algorithm, developed by Google for Tri Alpha Energy. Tri Alpha is working to develop practical nuclear fusion technology, a source of clean, near-limitless energy which has been the stuff of science fiction for decades. Doing so requires intensely complex calculations, weighing up thousands of variables for each test run of their experimental reactor thousands more than any human researcher could meaningfully evaluate. But the scale of the problem means that a purely programmatic approach could also lose itself down endless branches of an infinite tree of possibilities, without meaningfully improving the result.
The solution designed in response to this problem was for a machine-learning algorithm to methodically evaluate many options and to present a reduced set of possible actions to a human operator. In this way, not only were more minds brought to bear on the problem, but also at least two distinct ways of thinking: the programmatic, mathematical evaluation of the machine; and the creative, hunch-driven exploration of the human mind. The algorithm works less like a blind, rule-based machine and more like an optometrist trying out different lenses, constantly checking in with their patient, Better like this? Or like this? More like this, or like this?
The results are promising but what would such an algorithm look like if it were to appeal not just to the human, but to the more-than-human? An algorithm which devolved part of its processing, part of its thinking, to non-human actors: perhaps something like the bucket of pre-processing water described earlier, or the use of slime moulds and mycorrhizal networks as translators and co-creatives. This would be the full realization of Stafford Beers U-machine, or Turings o-machine and crucially, it would be facing outward, rather than trying to trap its colleagues in a little box, further disconnected from the wider world.35
An example of a really unknowing cybernetic machine is the Cockroach Controlled Mobile Robot, or Roachbot (20042006), Canadian designer Garnet Hertz a device created by the that demonstrates all of the above principles, while also retaining some of the more nightmarish aspects of the spinal dog and the crab computer. (Perhaps we might consider such squeamishness a useful indicator of more-than-human effectiveness, but that is a subject for elsewhere.)
The Roachbot consists of a motorized tricycle, a set of proximity sensors and a very large Madagascan hissing cockroach Velcroed to a trackball. The Roachbot uses the cockroachs dislike for bright light the same mechanism which sends them scurrying away when you turn on the kitchen lights to create a simple, exploratory cyborg robot. As the cockroach scurries on top of the trackball, it propels the tricycle across the room but if it gets too close to an obstacle, bright LEDs illuminate in that direction, causing it to spin off on a different trajectory. In this way, it makes its way around a space, avoiding obstacles in much the same fashion as Grey Walters tortoises. The key difference between the Roachbot and the tortoise is that an element of the system remains unknown to us. Unlike the tortoises, the cockroach at the heart of Hertzs machine has not been constructed or solved. Its doing its own thing it is an oracle. It has in cybernetic terms, been entrained, but it has not been dominated (although the cockroach itself might argue with that assertion).36
In any true relationship based on unknowing between human, machine, mushroom or cockroach the participant must forgo any requirement to fully understand the operation of any other. Rather, relationships based on unknowing require a kind of trust, even of solidarity. They require us to open ourselves to the possibility not merely of other intelligences, but to the idea that they might want to help us or not and thus might predispose us to the creation of more mutually agreeable conditions in which they might deign to assist us voluntarily. This is indeed the opposite of helplessness: it makes possible the creation not merely of better relationships, but of better worlds.
## Question for Al & Jian
Loading…
Cancel
Save