[hinkley]

Bruce Eckel (Thinking in Java) gave a presentation to the Seattle Java User’s Group sometime around 2008. I thought he would talk about Java things but he surprised us by talking about how annoying it is to get code snippets into books. He had interns writing a tool to extract live code and plop it into the book. It was something very similar to the tool I would find in jcite a few years later when my team had a bullseye on our back for being the only team close to on schedule (because we were using dev processes that were industry standard but not company standard and that pissed some people off).

They pointed out every place we weren’t following The Rules and one of those was that we weren’t creating a developer manual for people to use our library. Which was somewhat fair except I’d already walked people on every team through it, in person with a sequence diagram for doing their part of the workflow. But that was going to take me days of busy work every release and suck all of the joy out of my life. It was a clever chess move.

So what I did instead was fix our functional tests to be compatible with JCite, mash the printed form javadoc and some wiki pages together, and shoehorned them into a template of the corporate document format, programmatically. I couldn’t quite get the footers and indexes right, but I asked our less senior tech writer if she would be okay having to spend an hour fixing typesetting problems every release and she agreed. So instead of two developer days it was one hour of typesetting, by a tech writer. It took almost a year to break even on the time investment but it was well worth it in the long run.

To draw this curvy line back into a circle, I would think it perfectly reasonable not to utilize type inference in a functional or integration test. For the reason that you’d want something to break that tells you that you have a breaking change in this release.

[kqr]

Generating documentation from working code – as long as it's not at the expense of quality descriptions – is by far the superior way to make documentation. Every time I have not done that, the examples have become outdated within a year.