Dirt Simple Example

When shipping a software library, one should provide a set of examples (gosh, possibly even UnitTests!).

However, one of those examples should be simple. It should be the minimum number of lines required to warm up and execute that library's core feature.

For example, the minimum code required to run CppUnit is at DirtSimpleCppUnitExample

See also HelloWorld.

---

One of the best tech books I ever had was a "command reference" Microsoft Press book on dBASE III. Every command had a little code example that did a great job of illustrating the given command. The author clearly put a lot of time into the examples to make them clean, short, to-the-point, commented, practical, and illustrative of the concept of the operation without ambiguity. Plus, there were a few "nifty tricks" included to entice the reader. Further, some of the more involved commands took the time to present multiple examples. The author knew when to be short and when to be long, which is something that others often get wrong.

Documenting a command in a dictionary-like fashion by describing it, its parameters/options, and output type is generally pretty dry work with not a lot of room for variation and creativity (although it was included here also). However, selection and creation of the examples takes skill, creativity, experience, and art. The book examples were so good that I didn't need a "chapter book" on the subject. The command reference with the examples was sufficient. The commands were ordered entirely alphabetically, as apposed to categorized, so that I could quickly look up any other commands in a given example. I've seen other books and on-line references with a similar layout, but their examples usually sucked.

One has to think about the "essence" of the operation/command and its most common usage. Then one needs to brainstorm several candidate examples, then choose the best, which is generally the shortest one that's still relevant and clear. After it's selected, then work it further by tuning the comments and variables names (if relevant) to be concise. A common running sample application or domain also helps, such as a snow-board store or CampusExample. Giving caveats and common gotcha's can help also. This requires the ability to predict what tends to trip people up. Having direct training or tutoring experience helps here. Let the draft sit a while as you work on other commands. Then when you come back to it to review it, you'll see it with fresher eyes. (Mucking in tree-level details tends to take away one's ability to notice forest-level issues.)

Also be smart about when to show output. Many authors use blunt conventions such as "always show a result screen", which just creates bloat. If the result is obvious, consider omitting or merely describing output. For example, if the sample is "delete student number 1234", you don't need to show a before and after listing of students. And sometimes you can simply describe the output as comments. Here's a C-like illustration:

 print(3 + 2 * 4);  // result is 11

I think this is the book:

http://books.google.com/books?id=3GBJAAAAIAAJ

I once considered writing an SQL book using its style, but SQL is not really command-centric unless you target a specific dialect. Perhaps a SmeQl book someday :-)

--top