The challenge of keeping example code updated and working when it is destined for printed form was addressed during my update over the weekend with a quick glimpse into how we’ve overcome the problem. In a nutshell, we keep our example code in source control, and use brief tags in Microsoft Word along with a Word macro that pulls the code directly out of source control and places it inline with our descriptive content. See my previous article for the technical nitty-gritty.

Now I want to highlight a couple areas where I think this approach will be applicable, as well as a demonstration movie showing how we use it.

1. Technical Books. Big, big problem. I can’t remember the last time I picked up a programming book and didn’t find a flaw somewhere in the example code. Just like we have a spell-checker to catch a good portion of typos, we can now have a compilability-and-testability-checker, since our code would be coming straight from source control, where the automated build system and suite of unit tests made certain everything was working.
   
   And really, knowing that the printed code works is only a small benefit of this approach. I see a much bigger benefit being when edition 2 of a book comes out, and now making all of the code in the book up to date is as simple as… making the actual code in source control up to date. Then just run the macro to pull the new code into the book. Much, much simpler than having to go through the book and manually update all of the code examples.
2. Web Sites. This might be even more of a problem than with the technical books, since there often isn’t quite the same review process for web sites as there is for mass-produced technical books.
   
   Probably about 90% of the work I had to do to make this happen in Word was spent overcoming my own lack of knowledge in macro development and VB/VBA. This would have been significantly easier for me to have implemented with server-side software that I am more accustomed to; but alas, that was not where I needed it the most. I needed to address our printed documentation. I leave it to someone else to benefit in the online world of code examples.
3. User Guides and Developer Guides. I think I beat this one to death already. Let’s move on to the video.

Here I walk through the API manual for our WebReboot Enterprise, and show how a technical writer would add code examples into their documentation, and have those code examples come right out of source control.