One of my favorite funny cube posters was one a friend of mine had in his cube at a prior job. "Documentation? They call it code for a reason." I will admit that I once had a certain amount of programmer chauvanism when it came to documentation. Other than API docs, I had always found "grep" to be much more useful when it came to finding out what I wanted to know.
In part, this attitude was enforced by the state of documentation throughout the software world. Why bother reading documentation if what you want isn't there? Why isn't the documentation better?
About a year ago, I got it in my head that I wanted to know what BitBake, the system that runs the Poky build system (and OpenEmbedded and OE-Core) did under the hood. Specifically I wanted to know more about how BitBake figured out its dependency chain and task execution queue. Searching for documentation, I found quite a bit of end user documentation but not a lot about the internal workings. After looking at the code, I quickly realized that this would be somewhat time consuming to do in my spare time so I shelved it, promising myself I'd make time to do it in the future.
Last June I was contacted by Greg Wilson, one of the editors of 'Beautiful Code', with a request to contrbute a chapter to 'The Architecture of Open Source Applications vol 2'. After thinking about it for a bit, I knew this would be a perfect time to get to learn all those bits of BitBake I was curious about.
I spent the next month or so tearing through BitBake, both the current version and the initial release, learning more than most want to know about how it works and examining it's evolution. After getting a fairly good grasp on it, I sat down to write about it... and almost immediately got stuck on the first section.
Writer's block is an awful, frustrating experience. Compound it with trying to translate from code to English, and it is a migraine inducing task. Attempting to look at code that you didn't write in order to document what it does and the logic behind why it was done the way it was turns out to be a lot harder than I had anticipated. It took about two months of weekends to stumble through writing about the creation of the data store, the task exectution queue, the IPC, but 5000 words later, I had a pretty decent overview of what BitBake does during what is the first 20 seconds or so of a build (which is quite a bit actually). I am still humbled by the experience.
The Yocto Project is very fortunate to have a dedicated Information Architect, Scott Rifenbark, who creates all of the Yocto Project's documentation. He does a wonderful job and one of the things about Yocto I'm proud of is our dedication to good documentation.
I no longer ask myself why the documentation for something isn't better or accurate. If the state of documentation in the software world is ever going to change, it can't rest on the shoulders of the technical writers. Software developers need to get behind making it better. So, I've made a promise to myself; to try to be better at documenting the code I write. Every new bit of functionality I write, I'll attempt to document. Every bit of old functionality I touch, if I find that there is no documentation on it, I'll try to correct.
Special thanks go to Richard Purdie for answering all my questions and Chris Larson for sanity checking the chapter.