@ -9,9 +9,9 @@ Whenever too much technical proficiency is required to even read the documentati
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 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.
@ -23,7 +23,7 @@ The series _Programming Projects for Advanced Beginners_ by Robert Heaton embrac
A lesson can be learned: sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about all of these at once. Programming is about balancing these different aspects depending on the situation. Keeping this balance in mind when writing code documentation gives to the writer room to adjust the tone, intensity and approach depending on who will be reading these docs.
### Programming language
@ -58,7 +58,7 @@ Toxic geek masculinity reinforces stereotypes such as gendered roles in programm
Writing documentation is demanding. It's more delicate than programming, and requires a whole set of skills not usually treasured by the dev community. A kind of emotional intelligence and sensitivity that is far to be found in the competitive and pragmatic wastelands of the IT industry. Nobody here wants to write documentation, or pay anyone to do it. As a result, in a world where software thrives, documentation still seems to be a scarce resource.
It's ok, someone could argue, every question that can be asked on Stack Overflow, will eventually be asked in Stack Overflow (versioning Atwood, 2007). The popular Q&A website for developers is just an example of digital knowledge as a shared effort, together with the endless mailing lists, forums, discord servers and dedicated sources for whatever topic. It's astonishing how online communities can tackle any problem in no time.
@ -88,9 +88,9 @@ When you open the browser inspector on the Facebook website, you are confronted
`welcome.js` (2016) is a small gesture in response, a tiny javascript library published open source on GitHub under a permissive MIT license, where Bridle injects some greetings into their website (and in all the websites that include the library) to welcome users to the browser inspector. The artwork is hidden below the surface of the website, printed in the console of the browser inspector, a tool that allows users to see the underlying code of the website they are visiting. From here it provides some guidance for newcomers to access, inspect and modify the source code of web pages. A process that opens doors and lets people in, giving them more agency by demistifying technology.
Whether in a large project or a small gesture, attention to language can be transformative. In code documentation it can help deconstruct the false dichotomy between programmer and user, or pro and _newbie_. It can create spaces that feel safer, where people are invited to participate, express themselves and contribute to the community. It can help undo the impostor syndrome that affects many programmers, and that feeds on some hidden and inaccessible fundational knowledge that is nowhere to be found in code documentation. It can help shed some light on the massive amount of work that goes into the making of software: recognising all contributions, not just those of engineers.
@ -102,7 +102,7 @@ There's a multitude of ways in which changes to the codebase affect the document
In addition to the technical aspects, the editorial work needs to be taken into account. Adjustments and corrections and line-editing, clarifications of convoluted paragraphs, rephrasing of confused sentences, highlighting of important passages. Some projects support internationalization, and the contents are translated and adapted to different languages' structures.
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.
@ -126,9 +126,9 @@ At the very first encounter with a new script, details about its source code are
For example [Vue.js](https://vuejs.org/guide/essentials/lifecycle.html#lifecycle-diagram), a popular library for building web user interfaces, uses a diagram to explain the lifecycle of its components: when data is received from the server, when an element is rendered on screen, and when it disappears. What at first feels like magic, gradually becomes clearer. To present a structure means also to offer a way of reasoning about it. The reader gains a certain understanding and agency over the tools they are about to use.
Code documentation is not just pure introspection. Consider the diagram created for the _Padliography_, a bookmarking system for collecting links of otherwise scattered _Etherpad_ documents. It not only describes what's going on in the code, but also taps into its surroundings: the _Soupboat_ server and the _XPUB and Lens Based wiki_.
@ -144,7 +144,7 @@ The devil is in the details, and software as well: the translation between human
Documentation is not just for beginners: it's a code companion. You never stop reading it. Even experienced programmers must consult the docs when first encountering a software, and return to it when they need a refresher on the syntax of a particular command. They are continuously looking at code from multiple distances: close to the source code through lines of comment, or from printed books, along with pages of explanations and use cases.
This tentacular surface can reach a programmer at different moments of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the variety of forms that documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring diagrams and drawings. Daniele Procida proposes a systematic approach to organise this wealth of formats (2017). His framework focuses on the needs of different types of readers: by leveraging between practical steps and theoretical knowledge, he charts four main modes of technical writing. Each format has its own approach and intentions, and answers different questions.
@ -32,7 +32,7 @@ The Queer Motto API is published in the form of an Application Programming Inter
One example is the paradigm of the constant availability of the server. Behind every _SaaS_ there are always a server: the so-called _someone else's computer_ working behind the scenes. The seamless cloud picture of big tech rarely includes these machines, which are abstracted and hidden from the user. Instead, in the Queer Motto API, the presence of the server is a key aspect, especially when it decides to take a nap or refuses to work because it is on strike. These behaviors are documented with various error codes, giving developers using the API a way to make their applications react accordingly, and even join the cause.
@ -43,7 +43,7 @@ a workbook dedicated to the alternative text descriptions that make web images a
Websites are made of HTML, a markup language based on tags. Each tag represents an element of the document: a header, a paragraph, a link to another page, an image, and so on. As in a sandwich, these tags can be composed together, and organized to structure the contents of a web page. Every tag comes with particular attributes, and the image `<img>` one requires the developer to specify the source `src` of the picture to display. Here is also possible, but not technically mandatory, to add an `alt` attribute, with the alternative description of the image used by screen readers and other assistive technologies.
```html
<imgsrc="../img/workbook.jpg"alt="Big text fills the cover: ALT-TEXT AS POETRY. Each letter is made of repeated round shapes. The cover is printed on a subdued green paper, the inside pages are a soft white color, and the whole book is bound with a plastic, forest green spiral coil.">
@ -68,7 +68,7 @@ However, an implementation-first approach is not always an option, and code docu
In the discussions surrounding the development of this open source project, contributors began to consider how to encourage the use of this feature. From an initial suggestion to make it a requirement for Sketch to run, opinions settled on conveying its importance from the documentation, by adding it to the default template, and to the examples in the documentation and tutorial.
### Situated docs
@ -122,7 +122,7 @@ class Humor(Bureau):
```
Sample from `jokes.py`, the module of the _Department of Humor_. Here two _docstrings_ describe the bureau itself and the `Fortune Cookie` command.
In the essay _Chimeric Worlding_, researcher and designer Tiger Dingsun explores what graphic design can learn from poetics to escape a condition of pure functionalism. Graphic design and code documentation are similar: both deal with the organizazion and presentation of information, making meaning through the configuration of different elements, which are not just limited to language and text, but can also include images, symbols, (code snippets, examples). With a find&replace to swap all occurences of `graphic design` to `code documentation`, Dingsun's essay can be versioned to get an interesting perspective on what's happening in the Screenless Office.
@ -142,11 +142,11 @@ Tipically an API's architecture is centralised: there's a grand scheme and every
SI16 has been a space for undoing the grand scheme and let a plural, vernacular autorship to emerge. On the server side the API is structured as a filesystem, and to insert a new function it's enough to upload a Jupiter Notebook file containing the script and its documentation. Jupiter Notebooks are interactive documents in which code snippets and their explanations can be interwoven. They come handy for prototyping and documenting learning processes, writing code to be read not only by computers, but also by other programmers, in a paradigm also known as _literate programming_, introduced by Donald Knuth in 1984.
The title of the project was a declaration of intents: when approaching the technical be confident, be ambitious, and be ready to fail a lot. With these notebooks we were able to keep different voices visible in the documentation, to question a rigid and centralised structure, creating space to document and code from multiple perspective.
