diff --git a/chapters/00_intro.md b/chapters/00_intro.md index de2c974..c905f9d 100644 --- a/chapters/00_intro.md +++ b/chapters/00_intro.md @@ -1,46 +1,38 @@ ## 0. Intro -!!! note "structure for intro" - code documentation entry points and backdoor - relation between these two: - nature of code documentation is to create entry points - but actually there are a lot of issues around these entry points - because of approaches, language, formats, economies - so it's worthed to search for other ways in - enter backdoors - ways to infiltrate programming practices - inject different values and contexts - to open even more entry points - - - - -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. There are two flows around code documentation: -![entry point with a roster / backdoor with a barn owl](img/backdoor.jpg) +![The outline of a square in the 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.") `Flow #1` Documentation broadens participation in the making of software: lowering barriers and offering entry points for people to understand and attune with code. `Flow #2` -Documentation as a backdoor where to inject political aesthetic into software: to host principles in close contact with algorithms, letting them entangle and shape each other. +Documentation as a backdoor where to inject context into software: to host principles in close contact with algorithms, letting them entangle and shape each other. 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. 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 nature of code documentation is to create entry points for people to participate in programming practices. To encode and filter knowledge, and ultimately to share it with others. This "nature", however, does come not without issues. It makes a lot of assumptions on who's reading, expecting experts, or engineers, or dudes. Its language if often unwelcoming: too dense, too technical, very gendered and unable to address anyone apart the neurotypical-white-cis-man. It requires an huge amount of care, energy and time to be maintained: always out of budget, always as side project, always at the end, and only if there's time left. + +These problems will be addressed in the Entry Points chapter. + + +Even doing a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface that stretches through time and space. Time because it meets programmers in different moments of their life: from the first _hello world_, till the _how to uninstall_, it affects thinking about software continuously, and from different perspectives. Space because it comes with many different possible formats, and can shapeshift to serve diverse occasions: from simple `.txt` files to entire websites, from coding workshops to comments in the source code to hours of video tutorial. + +The question then is: can we make use of these backdoors to infiltrate programming practice and open more entry points from the inside? + +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, it seems to be an ideal surface to influence practices of software development. The second chapter brings some examples to illustrate how documentation can be used to orientate code in the world, addressing politics of participation, representation, and authorship in programming. The case studies comes from diverse realities, and in different scales: big collaborative projects as well as small, personal gestures. +With their molteplicity, they show how of blurred the boundaries of code documentation are. A lack of fixedness that can be used in turn to mold our wishes and values into it. + +A 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. + -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 inclusion and exclusion in the making of software. It is slippery matter, practiced with a range of different approaches, from artistic practices to digital activism. 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 and create most of the context around code. -The concepts of worlding, political aesthetic, and critical thinking can be applied to all sorts of technical manuals. However, the approaches and methods explored in this thesis are mostly informed by practices related to code documentation. While reading, please bind the terms software, application, program, etc. to code. Software documentation? Code documentation. -Next is to unwrap what does code documentation mean. In these writings the term refers to a set of different practices: from technical manuals to coding workshops, from comments weaved with lines of code to video tutorial. Code documentation is a technical object itself, one with very blurry boundaries. A lack of structure that can be used in turn to mold our wishes and values into it. We shall look at these practices with multiple lenses, in order to gather insights from various contexts. -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. -This thesis explores code documentation as an interface. A permeable passage from context to code, and from code to context. + -The first part focuses on languages, formats and approaches of code documentation, to broaden participation in the making of software by questioning 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) A backdoor to inject context around technical and non-technical choices. + diff --git a/chapters/02_backdoors.md b/chapters/02_backdoors.md index 8bdf612..05ee5dc 100644 --- a/chapters/02_backdoors.md +++ b/chapters/02_backdoors.md @@ -15,7 +15,9 @@ It's an approach that helps us to think about software as a cultural object. Som An object that, in turn, can be used to probe its surroundings. Who is developing? Who is going to use it? Who is paying for it and why? How is it structured? It is a big and centralized system or a loose collection of small and interchangeable tools? How long is it supposed to last? How can be fixed if it breaks? -The main focus of this chapter is to explore software documentation as a surface where these kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. A way to situate programming in specific contexts, but also to inject our contexts into programming practices. Hence the idea of code documentation as a backdoor: a passage to infiltrate software culture, to change things from the inside and create more entry points. +The main focus of this chapter is to explore software documentation as a surface where these kind of questions can be addressed. A place where the complexity of code doesn't blackbox ideas, and choices behind development can really be open source. + +A way to situate programming in specific contexts, but also to inject our contexts into programming practices. Hence the idea of code documentation as a backdoor: a passage to infiltrate software culture, to change things from the inside and create more entry points. ### Documentation & distribution