@ -22,31 +22,40 @@ Documentation is a way to produce narrations around software. To create a world
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`
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!
Keep in mind that there are many kinds of reader! Beginners and experienced programmers alike. Friends and strangers. Future selves. Everyone reading the same documentation, but from a diverse perspective!
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!
This does not mean that what you are writing has to meet the needs of everyone everywhere all at once. Rather, it's a way to acknowledge that different readers come with different expectations.
see diataxis
Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering some code, and return to the references when they need a refresher on the syntax of a particular command. They continuously look at code from multiple distances.
A useful resource to navigate programmers' needs with documentation is a framework proposed by Daniele Procida. By leveraging between practical steps and theoretical knowledge, it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
Tutorials offer entry points for the newcomers, while explanations unveal core mechanisms for more navigated readers. How-to guides teach how to get the work done, while references report lists of information ready to be consulted. Different documentations for different readers for the same code.
A good way to start is commenting directly in the source code.
Another way to start is by commenting directly 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.
There are many constraints here: no formatting, limited space, no way to insert images, an exagerate level of technical details, etc. For sure (for sure?) not the place to write an entire manual. 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.
Code and comments have their own pace, flow and logic. One does not read code as they would read a traditional text (debatalbe)! 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.
There are many possible strategies: order the comments progressively, rearrange the functions to follow a more sequential development, organize the code into blocks, link to external references, etc.
<!-- knuth intro of literate programming -->
### Start from an image!
@ -54,7 +63,7 @@ Reading source code feels like being an ant walking on a big painting. You can s
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.
Flowcharts and Nassi-Schneiderman charts are traditional options in technical writing, but things don't have to be sooo strict and rigorous. Let your visual intelligence and the ones of your readers hangout together. Offer other ways to think about code: sometimes it's easier with a concrete metaphor!
![chae api]()
Explanation of an API by Chaeyoung Kim
@ -62,4 +71,27 @@ Explanation of an API by Chaeyoung Kim
![frogs]()
Lifecycle of an etherpad document when stored in the Padliography.
![nassi schneiderman]()
### Start with someone else!
Teaming up with others comes with several benefits!
Teaming up reduces the workload on the individual: writing docs is demanding and delicate. It requires focus and care and energies: it's like gardening, or orthopedics, or cooking, or policymaking.
Teaming up offers multiple pairs of eyes to keep track of code. Here, even before releasing the docs, it's necessary to find a middle ground between different perspectives. Beginner and experienced programmers can write docs together! The process is beneficial for both, and the resulting docs comes with more facets.
Teaming up comes handy to undo assumptions and to open more entry points. A shared effort is already a moment of publishing. Making meaning together. A way to join different knowledges and skills, to broaden participation in the making of software.
## Pairing docs and code
Where to publish the documentation is up to you, and depends on the context your coding with. It could be close to the source code, such as a txt file in the same directory, or a ReadMe in the git repository. It could be more detached and physical: a printed booklet, a poster on a wall, a cheatsheet of references.
The one and only important thing to keep in mind is: pair docs and code.
Documentation is unfortunately just a snapshot of how a system work. A snapshot situated in a particular moment of time, referring to specific versions, implementations and languages. Be sure to offer this context to the reader! State to which version of the code this documentation refers!
Even worse than not having documentation, is to have docs that feel wrong, and don't match with the code they are documenting.
Here the making of software resembles gardening: code changes continuously, and overflow the specifications of a manual. With care and effort, documenting means to trim and prune and transplant and bend code and explanations together.
