On Documentation
I'm part of the Alloy (1) board and am responsible for "outreach and education", which mostly means I ask people what they find annoying about the tool. Part of my duties is I've gotta write some documentation so people can learn how to use Alloy without buying the book (2). I've started drafts and have run into a small but interesting problem: what kind of documentation should I be writing?
We get that there's different classes of people who are using documentation. Some are beginners, some are competent practitioners, some are experts. Obviously they need different content. But the layout of the content is important too, depending on who's reading it. Let's assume we have two topics, A and B. B requires some knowledge of A to understand. A has tangential topic A' and advanced topic A². In what order should we present those four things?
For a beginner, the important thing is scaffolding: each topic should be as small and independent as possible. That way they can comfortably build their mental model without having to memorize and distinguish extraneous information. That suggests a good ordering would be A B A² A' or A B A' A². We might even want to split A into Aa and Ab, and teach Aa B Ab A² A'. Whatever helps them learn the best.
For people who already have experience, it's gotta be A A' A² B. This keeps things conceptually grouped. If I need to find out more about the semantics of A, I don't want the docs to suddenly veer into B before getting back to A'. Now consider if A² also has a tangential topic, A²'. Depending on what I'm looking for, it might be more useful to me to have it organized as A A² A' A²', to keep the "tangential topics" grouped. This is also totally valid.
None of this even gets into content. Beginners need one kind of content which changes how we connect the topics to each other. For competent practicioners, you could have the content structured to suit the needs of "I already know this specific topic and need a reference" or as "I know the field in general but not this specific topic well and need to get better at it specifically." Like a tutorial, but one that already assumes they have built up their mental model. What you write depends not just one the level of the reader, but what they specifically aim to get out of being at their level.
Documentation is a hard problem! When people say they don't want to write docs, I kinda empathize. When people say they don't need docs for their project, though, I think they haven't thought through all the nuances of what documentation actually does. There's a lot of subtlety there.
Some other resources:
-
What nobody tells you about documentation: lots of people cite this. It breaks documentation down into four different types. I think they don't go far enough, and I kinda want to write a post called "the 27 types of documentation". Also their analogies make me think they haven't cooked before. C'mon, you can't give "an encylopaedia article" as an example of a "reference". We've got flavor bibles for a reason!
-
Teaching tech together: A very good intro to teaching for outsiders. Really changed how I do my workshops and plan documentation.
Housekeeping notes: "Programming Stuff" is the title until I think of something better. Other contenders are "Writing Driven Development" and "Time sucks and I hate it."
H
If you're reading this on the web, you can subscribe here. Updates are once a week. My main website is here.
My new book, Logic for Programmers, is now in early access! Get it here.