diff --git a/chapters/02_who_is_writing.md b/carpet/old_02_who_is_writing.md similarity index 100% rename from chapters/02_who_is_writing.md rename to carpet/old_02_who_is_writing.md diff --git a/chapters/00_intro.md b/chapters/00_intro.md index 7f188cf..7933198 100644 --- a/chapters/00_intro.md +++ b/chapters/00_intro.md @@ -1,14 +1,11 @@ ## 0. Intro +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. -How to create entry points for more people to participate to programming practices? -How to facilitate more diverse communities around coding? -How to acknowledge the value of different perspectives in the making of software? -Code documentation seems to be a crossroads where different knowledges meet in the making of software. A space that interfaces between the code, the user, the developer, and the world. A space where to welcome different voices: not just engineers, not just experts, not just dudes. A space where to acknowledge the massive labor of care besides technicalities, often marginalized by coding culture. - - -### Two flows +```note +is this first paragraph too declarative to be a research question? +``` There are two flows around code documentation: @@ -22,20 +19,17 @@ Documentation as a backdoor where to inject political aesthetic into software: t This research explores these two currents, with the thesis that code documentation is an ideal publishing surface to create worlds around software, and to orientate software in the world. -The first flow seems nothing new but the nature of every kind of technical documentation. To encode and filter knowledge, and ultimately to share it with others. Here documentation stands at a vantage point: by reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. Although, in order to make use of this sweet spot several issues need to be raised: documentation often doesn't feel welcoming for programmers others than dudes. Code documentation is still very gendered, and makes a lot of assumptions about who's reading. Addressing the problems of who is reading means also to acknowledge the counterpart of who is writing. Reading code documentation highlights that the making software does not stop with coding: that there is a massive labor of care besides engineering headaches, and that is valuable as much as technical contributions. +The first flow seems nothing new but the nature of every kind of technical documentation. To encode and filter knowledge, and ultimately to share it with others. Here documentation stands at a vantage point: by reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. In order to take advantage of this sweet spot however, several issues need to be raised: documentation often doesn't feel welcoming for programmers others than dudes. Code documentation's language is still very gendered, and makes a lot of assumptions about who's reading it. + +The second one is more labile and subtle: it deals with softer things than software. With political choices that inform technical details, with code close to codes of conduct, with power dynamics and forms of exclusion in the making of software. It is slippery matter, practiced with a range of different approaches, such as reclaiming spaces, enchanting tools and reassuring others. Reading code documentation highlights that the making software does not stop with coding: that there is a massive labor of care besides engineering headaches, and that is valuable as much as technical contributions. -The second one is more labile and subtle: it deals with softer things than software. With political choices that inform technical details, with code close to codes of conduct, with power dynamics and forms of exclusion in the making of software. It is slippery matter, practiced with a range of different approaches, such as reclaiming spaces, enchanting tools and reassuring others. ```placeholder -And these different techniques will be addressed in the second part of the thesis. +And these different aspect will be addressed in the second part of the thesis. ``` ### Coding contingencies -```todo -- elaborate on references -``` - How do you choose a particular programming language, a coding paradigm, a development environment, an infrastructure where to run the code, and so on? These are not just technical choices, but rather coding contingencies. The IT class in a public school. The job requirements for working in a tech company. An Arduino board received as gift for birthday. A colleague passionate about experimental music that drags you to a live coding concert. @@ -56,19 +50,15 @@ The concepts of worlding, political aesthetic, and critical thinking can be appl ```placeholder Some examples of documentation, different types and intensities -``` +``` Another term to contextualize (and dismantle?) here is _developer_. By stripping down every trace of professionalism and formal education, let's agree that a developer is someone who tinkers with code. No matter at which level, nor distance, nor experience. No matter if for work, for fun, for study. No matter if one is actively involved in the development of a tool, or comes from the user perspective. Ellen Ullman writes that programming is a disease, but the situation is even worse: code is contagious material, touch it once and you are a developer. -```note -Next three paragraphs are to readjust a bit after the new structure: chapters 1 and 2 are merged and are a first part about entry points. -``` - -This thesis explores code documentation as a publishing surface. +This thesis explores code documentation more as an interface then as a publishing surface. A permeable passage from us to code, and from code to us. -The first part focuses on who is reading, who is addressed, and who is left out. Code documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation. By reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. +The first part focuses on who is reading, who is addressed, and who is left out. Code documentation brings an understanding on software by disclosing its magic. It reveals what can be done with it, and where are the limits. By lowering barriers and creating entry points, documentation broadens participation. By reaching not just beginners, but experienced programmers as well, it affects thinking about software continuously, and from different perspectives. In order to create accessible entry points and speak to different people however, it's necessary to question the usage of language, to criticize the amount of energies required for writing, and to address problems of inclusivity within tech communities. -The second section is focused on worlding, and the relation between code, documentation practices and political aesthetic. 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) +The second section is focused on worlding, and the relation between code, documentation practices and political aesthetic. 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) A backdoor to inject context around technical and non-technical choices. diff --git a/chapters/01_who_is_reading.md b/chapters/01_entry_points.md similarity index 89% rename from chapters/01_who_is_reading.md rename to chapters/01_entry_points.md index cf30e69..02d750a 100644 --- a/chapters/01_who_is_reading.md +++ b/chapters/01_entry_points.md @@ -1,18 +1,18 @@ -## 1. Who's reading +## 1. Entry points ```note -code documentation as a publishing surface? +code documentation as a publishing surface to create entry points? yes because - 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 + 1.1 it's often first thing one reads when approaching software - see getting started + 1.2 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 + 1.3 it should be less hostile - see welcoming writing + 1.4 it should stop assuming reader - see natural readers ``` -### Getting started +### 1.1 Getting started ```note ("Getting startled" could also make for a nice title) ``` @@ -27,7 +27,7 @@ The introduction to a program situates it also within a larger ecosystem: how to The initial imprinting of documentation is a vantage point to orientate code in the world. -### A code companion +### 1.2 A code companion The devil is in the details, and software as well: the translation between human and machine has to be negotiated with all the specifics of a particular programming language or platform. Sometimes for the web, sometimes for a hardware component, sometimes for another operative system. These _specs_ make every piece of code a bit alien and peculiar. Tinkering with code is not just knowing by heart a programming language, but rather having to deal with a lot of different recipes for different occasions, and know how to adapt. @@ -44,12 +44,12 @@ A text that fails to address who's reading can result inaccessible and frustrati ```note think about: - move next paragraph in worlding chapter? -- unpack political aesthetic +- unpack political aesthetic or use a different term, not sure if there is the headspace to go into RancR atm ``` The same is true for the additional layers of meaning necessary for a process of world building. To enchant software with political aesthetic (Ranciérre through Soon and Cox, 2020) is required to operate at different scales. Within both public and private dimensions, with technical and social frameworks. During a workshop for example, people meet face to face. Here togetherness can glue technicalities as a paratext, questioning reproduction of knowledge and its power dynamics. (See for example _Feminists Federating_, mara karagianni, ooooo, nate wessalowski, vo ezn in Toward a Minor Tech - A peer reviewed Newspaper vol 12, 2023) (Note that the opposite effect is also true, with technicalities as paratext conditioning how people are together) -### Welcoming writing +### 1.3 Welcoming writing The potential of documentation to orientate software in the world clashes against some big elephants in the room, and tech culture should stop keep them in captivity. Sure, it would be nice if developers could rely on several kinds of documentation when approaching code. Unfortunately often there is not even one available. @@ -101,57 +101,32 @@ Message in console printed by Facebook to stop users - source: booktwo.org Message in console printed by Bridle to welcome users - source: booktwo.org -### "Natural" reader - -```note -- assuming a certain kind of reader - expert - dude -- references: - - programming for the millions (ullman, 2016) - - read the feminist manual (karagianni, 2021 ) -- bro culture ? ? ? - (could be the transition from previous section) - (could be the example with evvvvil help patches) -- refer to a specific cultural niche ? see ullman, even tho need to counter balance with other examples -- manuals often address just male developers -- often documentation doesn't offer entry points for beginners, or a sense of direction, this esp a problem with hypertexts -``` - -- who writes code documentation tends to assume a certain kind of reader, to talk a specific language, to refer to a particular context - -sections - -__expert reader, formerly educated reader__ - - - -- takes for granted the technical level of the reader - - -A whole range of different people read code documentation. - - -takes for granted a specific lexicon, - -relates with external sources without referring to them - - -__male! developer often addressed as he/him__ - - -- within a particular cultural niche! western -- dude - - - - - - +### 1.4 "Natural" reader +- Who writes code documentation tends to assume a certain kind of reader: +- expert, formerly educated reader + - takes for granted the technical level of reader + - takes for granted a specific lexicon, + - refer to a broader context or previous, not explicit references + - see programming for the millions (ullman, 2016) +- problems of language + - gendered writing and gendered roles + - developer often addressed as he/him + - dude culture and toxic masculinity + - example machism, vvvv twitter-api help patches + - example encoded chauvinism +- a whole range of different people read code documentation! + - again diataxis: different format for different levels + - offer guidance between milions references + - goat meme +```note +A couple of brainstorming paragraphs feel free to skip sorry for the inconvenience +``` Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers. @@ -163,11 +138,13 @@ Learn to code is like learning another language: not just a new bag of words and Coding means to express ideas with the reduced vocabulary of a programming language. -when writing need to share a way to think to software - - - - +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. +### 1.5 Documentation as gardening -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. +- Code documentation require as much maintainance as code itself +- Updates, corrections, additions, translations +- Massive amount of energy required +- Gendered labour +- Documentation as subaltern work (in open source projects) +- Post-meritocracy manifesto diff --git a/chapters/03_hello_worlding.md b/chapters/02_backdoors.md similarity index 100% rename from chapters/03_hello_worlding.md rename to chapters/02_backdoors.md diff --git a/queue.md b/queue.md index c7d01f5..31085e3 100644 --- a/queue.md +++ b/queue.md @@ -1,13 +1,15 @@ # What to read next? + - [A Research UNIX Reader: Annotated Excerpts from the Programmer’s Manual, 1971-1986](https://www.cs.dartmouth.edu/~doug/reader.pdf) -- Sphere 300 corporation user manual (the one Supi sent) +- Sphere 300 corporation user manual (the one Supi sent) (super gendered language) - [The Jargon File](http://www.catb.org) - [Strangest computer manual ever](https://ironicsans.substack.com/p/the-strangest-computer-manual-ever) + - [They dont make computer manual like this anymore](https://www.ironicsans.com/2010/02/they_dont_make_computer_manual.html#comment-403451) -- [Franklin Ace 100 user manual](https://www.ironicsans.com/ace100.pdf) +- [Franklin Ace 100 user manual](https://www.ironicsans.com/ace100.pdf) (see [birds press 05](https://git.xpub.nl/kamo/birds-press/src/branch/main/covers/05_Franklin-ACE-100-Operators-reference-manual.jpg)) - [Franklin Ace 1000 user manual](https://www.ironicsans.com/ace1000.pdf) - [knowing machines - critical field guide](https://knowingmachines.org/critical-field-guide) @@ -16,7 +18,6 @@ - [julia evans - wizard zines](https://wizardzines.com/) - [solarpunk - zines](https://solarpunk.cool/zines/) -- [Bridle - welcome.js blog post](https://web.archive.org/web/20200219181416/http://booktwo.org/notebook/welcome-js/) - [who called it “writing documentation” and not “manual labor”](https://mastodon.social/@NeoNacho/109980998747734857) - [documentation as harvesting](https://documenta-fifteen.de/en/news/harvesters-and-harvesting-practice-at-documenta-fifteen/) @@ -24,3 +25,7 @@ - [Lumbung tools](https://panduan.lumbung.space/s/9f7eb837-c8b8-4b64-ad68-a298bde8ab36) - [titipi methods](https://titipi.org/?methods) - [bug report geohacker](https://volumetricregimes.xyz//index.php?title=We_Have_Always_Been_Geohackers) + +- [pandocs history - the gameboy one](https://gbdev.io/pandocs/History.html) +- [gamembert](https://robertheaton.com/gamebert/) +- [programming projects for advanced beginners](https://robertheaton.com/2018/12/08/programming-projects-for-advanced-beginners/)