@ -12,12 +12,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 not come without issues. It makes a lot of assumptions on who's reading, expecting experts, or engineers, or dudes. Its language is 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. The first chapter will raise these points to remark how often code documentation acts as a barrier, gatekeeping access to the making of software.
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 about who's reading, expecting experts, or engineers, or dudes. Its language is unwelcoming: too dense, too technical, very gendered and unable to address anyone but the neurotypical-white-cis-male programmer. Documentation requires an enormous amount of care, energy and time to be maintained, and it's done always out of budget, always as a side project, always at the end, and only if there's time left. The first chapter raises these points to note how often code documentation acts as a barrier, gatekeeping access to the making of software.
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.
Even if it does a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface whose reach extends through time and space. Time because it meets programmers at different moments in their lives: from the _hello world_ till the _how to uninstall_, and it influences thinking about software continuously, and from different perspectives. Space because it comes in many different possible formats, and can shapeshift to serve different 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 practices and open more entry points from the inside?
The question then becomes: can we make use of these backdoors to infiltrate programming practices and open more entry points from within?
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 will bring 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.
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 software development practices. The second chapter presents some examples of how documentation can be used to orientate code in the world, addressing politics of participation, representation, and authorship in programming. The case studies come from diverse realities, and from different scales: large collaborative projects as well as small, personal gestures. In their multiplicity, they show how blurred the boundaries of code documentation are. A lack of fixedness which in turn can be used to mold our wishes and values into it.
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.
A term to contextualize (and dismantle?) in these writings is _developer_. Stripping away any trace of professionalism and formal education, let's agree that a developer is someone who tinkers with code. No matter what 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.
Documentation that assumes a certain kind of reader can result inaccessible. The recipient is often thought similar to who's writing: familiar with the topic, at ease with technicalities, and capable of cutting through the precise lingo and esoteric references offered as explanations. Eventually (and in most of the cases) who's reading happen to be someone else. This mismatch transforms entry points into barriers that filter out who can participate to coding.
Documentation that assumes a certain type of reader can result inaccessible. The recipient is often thought to be similar to the writer: familiar with the subject, comfortable with technicalities, and able to cut through the precise jargon and esoteric references offered as explanation. Ultimately (and in most cases) the reader is someone else. This mismatch turns entry points into barriers that filter out who can participate in coding.
Whenever too much technical proficiency is required to even read documentation itself, knowledge results inaccesible, and confined in the ivory tower. An important detail to notice here is that this is an antipattern that reinforces the segmentation between who is allowed in and who is not: only previously educated ones can access, while others are kept out. Not filtering information becomes a filter to who can engage with it. Contents need to be curated, that does not mean over-simplified or generalized, but rather made legible.
Whenever too much technical proficiency is required to even read the documentation, knowledge becomes inaccesible, and confined in the ivory tower. Not filtering information becomes a filter to who can engage with it, a backfiring practice that reinforces the segmentation between who is allowed in and who is not: only the already knowledgeable ones can access, while others are kept out. Contents need to be curated, that does not mean oversimplified or generalised, but rather made legible.
To cultivate legibility is but an easy task, especially when dealing with computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narrations and entwined plots and main characters at the same time. The purpose of an abstraction is to act as a symbol, as a mentally maneuverable concept, free from its technical implementation details. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up for the digital stack.
Cultivating legibility is not an easy task, especially when it comes to computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narratives and intertwined plots and main characters at the same time. The purpose of an abstraction is to function as a symbol, as a mentally manoeuvrable concept, free from the details of its technical implementation. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up the digital stack.
Take a course such the one presented by Noam Nisan and Shimon Schocken in _From NAND to Tetris_, where they slowly build a programmable computer able to run the classic game starting from simple logic gates, so basically from microchips and electronics. One layer after the other, from boolean operations with 0 and 1 to registers and CPUs, from machine language to high level programming. Here one can try to unwind the coil and start understanding programming from scratch scratch, but this approach is best suited to a university curriculum, and it's often not real effective when facing real-world problems, with real-world constraints, and real-world circumstances.
Take a course such as the one presented by Noam Nisan and Shimon Schocken in _From NAND to Tetris_, where they slowly build a programmable computer capable of running the classic game, starting from simple NAND logic gates, in other words, from microchips and electronics. Layer after layer, from boolean operations with 0 and 1 to registers and CPUs, from machine language to high level programming. Here one can try to unwind the coil and start understanding programming from scratch, but this approach is best suited to a university curriculum, and it's often not very effective when facing real-world problems, with real-world constraints, and real-world circumstances.
A deep understanding of technical systems is admirable and desirable of course, given the insights it can provide on the infrastructures that shapes our everyday lives. But it cannot be the only mode of access available. Deep understanding comes with its own learning curve, and it can be blocking for a lot of people. Yet, many, many guides resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, tracing back till the invention of the wheel.
A deep understanding of technical systems is of course admirable and desirable, given the insights it can provide into the infrastructures that shape our everyday lives. But it cannot be the only mode of access available. Deep understanding comes with its own learning curve, and it can be a barrier for many people. Yet, many, many guides resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, tracing back till the invention of the wheel.
A different kind of approach, more modelled on the way technology and coding meet us in real life, starts from the middle and tries to make sense of its surroundings. One could just need to make a website, for instance. And could just start doing that, following a guide or a tutorial. Soon questions would start bubbling up. Made from scratch or with a framework? And which one to choose? What about the backend? Where to host it? On which kind of server? Static or dynamic? And the Content Management System to upload new materials? And where to get the certificate for secure connection? These things surely are important, but there is no really need to know everything beforehand to put the website online. Programming is provisional: leaving TODOs in the code to come back later.
