4.3 KiB
Care for code - Documentation session
Two hours of headspace to write some code documentation. For your new coding project, for the cryptic library you downloaded recently, for a script that you want to share with others!
Too many pieces of code are left alone out there: without an entry point, forgotten, while outside is raining. Wouldn't it be nice to take care of them?
Enter the documentation sessions. Two hours where to sit with source code and write something about it. From simple instructions to in-depth explanations, or maybe some drawings to illustrate the overall process. You name it.
Writing documentation is tricky! But let's face this together: prompts and suggestions will be offered for inspiration, and coffee and snacks for restoration. If you want there will be space to share your work and exchange feedback, if not no prob: just enjoy the cozy music and write some docs.
These sessions grow out of the contradiction of being frustrated in having to deal with undocumented pieces of software, and at the same time never documenting anything. While for sure there is some thrill in understanding how to stitch codes together, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
At the same time, this very lack of documentation could be used as a starting point.
Documentation is a space that interfaces between the code, the user, the developer, and the world. A space with potential to renegotiate and reclaim given margins and entry points. A chance to overwrite what is normalized, and let more voices participate in the discourse that is software.
Documentation is a way to produce narrations around software. To create a world for the code to inhabit, to stretch what is possible to do or to think with it. Documentation is a space for the political in the software. A surface that could host ideas in close contact with code, letting them entangle and shape each other.
Ok ok ok ok but where to start?
One can start documenting code in many different ways. Every piece of software and every situation require something slightly different, so it's not that there's a right or wrong way to do it.
Here some prompts!
Feel free to add more ??? note that this could be an open repo
Start from the readers!
For who are you writing this documentation for?
Keep in mind that there are many different kinds of reader! Beginners and experienced programmers alike. Friends and strangers. Future selves. Everyone reading the same documentation, but from a different point of view!
When writing there's no need to take into account every possible programmer on earth: a piece of documentation does not need to satisfy everyone!
see diataxis
Start from the code!
A good way to start is commenting directly in the source code.
There are many constraints here: there is no formatting, there is limited space, there is no way to insert images, etc. These limitations however offer a good chance to focus and explain what the code is doing in the clearest way possible.
Code and comments have their own pace, flow and logic. One does not read code as they would read a traditional text! It's rare for a script to run in a linear fashion, from top to bottom: more often it jumps here and there, calling functions and methods scattered around the codebase.
Guide your reader!
There are many possible ways: order the comments progressively, rearrange the functions to follow a more sequential development, organize the code into blocks, link to external references, etc.
Start from an image!
Reading source code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective.
Sometimes an image is worth a thousand words. To illustrate the different steps of the process, or to give an overview of the program's lifecycle.
Flowcharts and Nassi-Schneiderman charts are traditional options in technical writing, but things don't have to be so strict and dry. Let your visual intelligence work for you.
Explanation of an API by Chaeyoung Kim
Lifecycle of an etherpad document when stored in the Padliography.