Skip to footer navigation.

« Oatmeal


Here are some scattered thoughts on writing and maintaining documentation. My experience doing this is wholly confined to software development, but I think most of this advice is general enough to make sense in other domains, too.

All text is hypertext.

One thing well

I think good documentation picks a lane and runs there. It doesn’t try to be everything for everyone all at once.

The lanes available:

Each of these maps fairly well to an audience:

Know who will be using your documentation, and try to understand how

Information architecture can make-or-break how usable documentation is. In order to create useful documentation you need an understanding for how folks will be interacting with your docs. What will the be looking to accomplish — related to the previous section, know your audiences’ goals.

Grade level is a terrible target

Never worry about grade level,” instead, focus on how long you want someone to spend reading a thing to understand it.