Comments on: Ever Use Example Code From a Book That Did Not Work?

By: At Home Jobs

At Home Jobs — Sat, 19 Jun 2010 23:38:39 +0000

Your site is excellent! The information you provide has helped me tremendously. Thank you for all of your time & work. Best Regards.

By: Cory Moglia

Cory Moglia — Wed, 16 Jun 2010 06:51:19 +0000

thanks to you for the previous entry.

By: Lincoln Davis

Lincoln Davis — Fri, 01 Jan 2010 03:30:53 +0000

Tech Question:
Q

By: Marge

Marge — Thu, 23 Oct 2008 01:24:09 +0000

People should read this.

By: Dave

Dave — Tue, 08 Jan 2008 20:30:08 +0000

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.

By: Cory von Wallenstein

Cory von Wallenstein — Tue, 08 Jan 2008 17:33:33 +0000

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.

By: Dave

Dave — Tue, 08 Jan 2008 16:44:57 +0000

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?