`Flow #1`
Documentation broadens participation in the making of software: lowering barriers and offering entry points for people to understand and attune with code.
@ -13,26 +13,12 @@ Documentation as a backdoor where to inject context into software: to host princ
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 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.
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 not come without issues. It makes a lot of assumptions on who's reading, expecting experts, or engineers, or dudes. Its language is often unwelcoming: too dense, too technical, very gendered and unable to address anyone apart the neurotypical-white-cis-male programmer. Documentation requires an huuge amount of care, energy and time to be maintained, and it's done always out of budget, always as side project, always at the end, and only if there's time left. These points will be addressed in the first chapter.
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.
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 which reach stretches through time and space. Time because it meets programmers in different moments of their life: from the _hello world_ till the _how to uninstall_, and 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 series 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.
<!-- This thesis explores code documentation as an interface. A permeable passage from context to code, and from code to context. -->
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 articulate 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 from different scales: big collaborative projects as well as small, personal gestures. With their molteplicity, they show how 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.
<!-- 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. -->
A term to contextualize (and dismantle?) in these writings 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.
