The Programs of a Third Week of Scribbling
This Week’s Program: July 24 - July 28
In the past couple of weeks I’ve learned how to build and write in Scribble, Racket’s metalanguage for writing documentation and manuals for programs. This week I continued that trend, but this time, learning how to automate this process.
You can now see a very early draft of Overscan’s in-progress documentation at http://www.markwunsch.com/overscan/
Why am I putting this all this effort into documentation? Several reasons:
- A program or library isn’t complete until it’s documented. In the case of a library like Overscan, the main interface is code, and the usage of that code should be documented. Otherwise, users of the library won’t know its capabilities.
- Much of the idea behind this very Tinyletter was to articulate my own progress and learning. A program’s documentation is an articulation of its context and its reason for being. The documentation is a forcing function to demonstrate why the code is.
- Writing documentation for a library can show the holes and gaps in a
library. If the program can’t be described well in prose, it
probably requires some different thinking. As I wrote some of the
documentation for
introspection
, I found that there were some concepts that just didn’t make sense when I tried to describe them. I can refine those APIs now. - Scribble is a big part of the Racket community, and using the tool and writing the docs show that Overscan belongs in Racket.
f68d7c34623a6209cb1e24ad19b88a332008bec8
If you followed along the development
of hive-city
you’ll know
that I just love Make. I write a
Makefile to run the Scribble program and generate the documentation
and put it in a docs
directory in the repo. GitHub Pages
treats the docs
directory a little special, and can use it as a
publishing source.
Write some docs and bada bing, bada boom they’re on the internet.
Next week I’m going to keep writing some stuff and then probably revise the program as I hit little snags where writing out usage reveals something funky in the API.
Have a good weekend!
– Mark