The Documentation Crawl

A phrase I use alot is "documentation crawl". I don't know if I made it up, but I think I did. At least, I'm pretty sure I didn't hear it somewhere.

What's a documentation crawl? Well, it's sort of like a pub crawl, but through the documentation of something. Actually, that's not at all true. A pub crawl kind of assumes jumping from one pub to the next. This is more like the opposite of that: going back to the same pub over and over until you've sat on all the benches and tried all the kinds of ale.

A documentation crawl is that, except for documents. It's rtfm but more sincere.

Here's how to perform a documentation crawl. Pick something you want to know. Read the documentation carefully, systematically, and thoroughly. Try not to skim. Maybe take notes. If you jump around, try to come back and cover the parts you skipped.

Normally, I find that I interact with documentation with a just-in-time and as needed mentality. I'm trying to find the answer to a specific thing, and I just want to learn the feature, function, detail, or example that lets me move forward with whatever project I'm working on. This is great for keeping moving, but it's terrible for really understanding. One thing I've noticed in my career in programming is that it's super helpful if you can really understand something, and documentation helps with that.

Example time. Last year I read several books on the C programming language. One of them was an overview of features in the latest C standards. It's not very exciting stuff, to be honest. I treated it as a documentation crawl. I went through every example in every chapter, set up a project and wrote tests for every standard library function. It was an excellent review, and at the end I felt like I'd accomplished something.

The interesting thing is that it's amazing how useful this approach can be. Sometimes you'll find something in the documentation that saves you time. You'll find a feature you didn't know to use, and would never have known to look for. You'll know that there's a standard library module for that, or an error hook. You may not remember exactly what or where, but your memory will jog on the idea that you've seen that before.

I can't stress enough how useful a documentation crawl can be. I've started combining them with projects and tests: code up all the examples! Answer the sample questions at the end of chapters! Write tests for all the methods of a class! Go a level deeper and look at the source code!

Try it. If you're like me, you'll be surprised at how satisfying it is. Rtfm!