Ever Use Example Code From a Book That Did Not Work?
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.
- 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. - 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. - 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.
Tags: developer guide, example code, technical books, technical web sites, user guide
Subscribe via Feedburner
January 8th, 2008 at 11:44 am
I’ve been doing the same thing with OpenOffice.org for a few years and we’ve been doing it with DocBook (and other various XML formats) for some time now. Several Wikis support pulling in code snippets via various mechanisms.
Is there something particularly new about your approach?
January 8th, 2008 at 12:33 pm
Certainly. The biggest differences to previous approaches and this approach are focused around ease of use both for the programmer and the technical writer, and for level of control of code selection.
DocBook, for example, makes it pretty easy to pull in entire outside files, but that is only useful when you’re showing a complete example program. What if you’re describing a method name inline in the content? What if you wanted to say:
“The doPowerOff method is used for doing A, B, and C.”
With other approaches, you really don’t have a way to say “insert this method name here” in the document such that when the underlying code is inevitably refactored (perhaps to doServerPowerOff), the references to those method names get updated inline too.
Even if you had an external file that just had that method name in it… for this example, with Java, that would not be valid and compilable, so its usefulness diminishes.
Even specifying by line numbers is far, far too brittle. By having the code identified with context-relevant tags, life is easier for the programmer moving code around, and the technical writer trying to figure out what-does-what.
Really, we needed a way to get down to an atomic level of control for what code gets pulled into the documentation, and we needed a way to keep the code itself valid and testable by our build environment, and most importantly, we needed to support code refactoring so the changes would automatically cascade throughout our documentation.
January 8th, 2008 at 3:30 pm
I built my DocBook files by embedding elements that would retrieve a file and look for commented “snippets” in any of a couple source control systems; the same thing in OOo (but via OOo scripting). It’s the same way the Wikis I use pull in external snippets and seemed the easiest way for my documentation and books.
October 22nd, 2008 at 8:24 pm
People should read this.
December 31st, 2009 at 10:30 pm
Tech Question:
Q
June 16th, 2010 at 1:51 am
thanks to you for the previous entry.
June 19th, 2010 at 6:38 pm
Your site is excellent! The information you provide has helped me tremendously. Thank you for all of your time & work. Best Regards.