You cannot think about code without thinking also about code documentation.
Programming is like walking in a room without turning the lights on. It can be a place you know by heart, but you still prefer to rely on some guidance, using your hands to sense the walls, and move through the furnitures without hitting your pinkie toe.
For code is the same: you usually appreciate some guidance.
Documentation can be as simple as a plain text file placed near the code. A `README.txt` that invites developers to take a look before diving into the program. Printed technical manuals have today transformed and spreaded into many different shapes: wikis and platforms and websites generated with various tools, each with particular focus and features.
This research explores two currents around documentation practices, with the thesis that code documentation is an ideal publishing surface to create worlds around software, and to orientate software in the world.
`Flow #1`
`Current #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`
`Current #2`
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 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.
@ -104,9 +104,7 @@ In addition to the technical aspects, the editorial work needs to be taken into
Documentation can be as simple as a plain text file placed near the code. A `README.txt` that invites developers to take a look before diving into the program. However, as projects become larger and more articulated, the need for more comprehensive and structured formats arises. Printed technical manuals have today transformed and spreaded into many different shapes. Wikis and websites generated with various tools, each with particular focus and features.
All of these platforms imply more work: maintenance, design and sometimes even guidelines and documentation for the documentation itself.
If a project is larger and more articulated, the need for more comprehensive and structured formats arises. Wikis, websites, forums: all these platforms imply more work: maintenance, design and sometimes even guidelines and documentation for the documentation itself.
Writing docs is not a once in a lifetime effort, but an ongoing commitment. It's a process with its own pace and timing, and much like gardening, it's a form of care both for the code and for the community around it.
