What is a good example project? What do you look for when you are reading documentation? Are you looking for a project that almost exactly resembles the problem you are trying to solve? Or, are you looking for something that is going to get you interested even if it might not seem directly relevant to your problem? These are some of the questions I’m asked by startups looking to seed a new project with compelling documentation. What examples should we use in our documentation?
Here are some strategies that I’ve seen (and some I’ve used) in my time writing documentation:
You can write hundreds and hundreds of pages in a very structured format like a cookbook and write a series of generic examples referencing apples and oranges, abstract numbers, and contrived “People” beans, or you can try to inject some levity and creativity into the effort and try to construct hypothetical examples all of which revolve around a central theme. I tend to find these engaging if they involve an area or subject matter that can hold my attention. In Maven by Example, I went with an example that interacts with a Weather API because I find that to be an interesting subject.
On a current book, I’m toying around with the idea of making all of my examples revolve around social networking because it is relevant to the problems facing developers today. On the other hand, social networking concepts are so familiar and well covered, this example might not stand out enough. Other themes that could get my attention would be something to track health and fitness, an example to keep track of earthquake response, voting systems, etc.
This sounds like a distraction: why write a book about Google Guice and distract the reader with a tangential example involving physics? The answer is simple, readers need to be engaged by something and writing a book with a complicated Hello World application is as boring to read as it is to write. Also, writing a book with boring examples doesn’t teach people how to think about architecture and design. When you teach people about a technology you can’t just focus on implementation, you have to anchor it in a real problem.
I’ve read books in which the author goes to great lengths to entertain with examples. See a previous section, I too was once convinced that the conversational tone of a technology book was a great place to entertain. My first book was full of attempts at tounge-in-cheek humor. After doing this for a while, I stumbled upon a humbling (and extremely important) realization: “no one is reading this stuff, and if they are they don’t want the distraction”. A first-time author is convinced that people are reading his or her book because it is full of helpful wisdom. After a few books, a good author understands that the copy exists simply as a hook for well crafted example code. In a technology book, the code is the primary artifact, the copy and anything it contains simply distracts from the technical content.
So, no taking the reader’s time to make some jokes is almost entirely unhelpful. I’ve written about this in the past, but the quirky, conversational tone of technical books was something that worked in the 1990s. These days, people don’t have time to follow your thread.
I did a bit of this in the Jakarta Commons Cookbook. My example code is riddled with references to current events and some of my code listings definitely try to make the case for environmental action. (“The following example compares the mileage of several popular vehicles vs. CO2 output from the exhaust.) I took some inspiration for this from Feuerstein an author who had a multi-year lock on writing all of the O’Reilly books on Oracle. To read a Feuerstein book is to read a manifesto on gun control, environmental action, and anti-war activism. While I didn’t want to get as “In your face” as Feuerstein, I did think it made some sense to appeal to people by referencing current events, popular albums at the time, etc.
The only person who noticed any of this was my brother Sean. He called me up one day telling me that despite his inability to understand the content of the book, he got the example references. I’ve soured on the idea of overtly political examples. They turn off a significant portion of the audience, and if your writing is ever going to be used in business you need to stay away from anything that might even remotely offend a customer. When your book’s examples reference Albert Gore and George W. Bush, you are also attaching a date to your material. Stay away from agenda-driven examples.
“In this book we’re going to implement a simple version of Twitter.” If the example is too simple, it won’t show a real-life example. On the other hand, the initial chapters of any technology book cannot be mired in the details of some contrived example. The reader isn’t coming to you for an exposition on the merits of a particular application’s schema, they just want to know how the tool or library works. On the other hand, I’m tired of writing books with “Person” beans, “Job” beans, and “Company” beans. An overly trivial, boring example is the non-descript, beige cubicle of programming examples.
On the other hand, the overly trivial example can be fully explained in a single blog post. (Like the blog post from yesterday which contained a real sleeper of an example.)
A “Real” Example
This might work for simple technologies, but the “real” world of enterprise software is often so large it would be impractical to simulate a real environment without writing multiple volumes that detail both the historical context of a particular enteprise and the massive amount of code and systems involved. Think about it. Could your book present an enterprise example that approximated a Google or a Facebook? Not a chance. At best, you’ll be approximating the complexity as seen by a single workgroup.
Sun Microsystems solved the problem by created the Java Pet Store. The idea of modeling the enterprise as a Pet Store never appealed to me, and this is probably one of the reasons why I paid absolutely zero attention to the Pet Store example. It would show up everywhere, in conference presentations (“using the Java Pet Store as an example”), in vendor marketing (“to demonstrate our product, we’ve implemented the Java Pet Store”), and I believe it was also a way for people to demonstrate the value of patterns. Google for “Java Blueprints” and you’ll see that the “Java Pet Store Reference Application” is freely available under a BSD-style license. Selling parrots online never struck me as a killer app. It was never something I could unpack for a client and demo. “Check this out, see how easy it is to add a new cat to the inventory.”
Unless your product is defined by performance, writing an example around a performance spec is a real sleeper. You can write an application that demonstrates transaction speeds using http://www.tpc.org/tpcc/, but, again, these examples strike me as being very, very dry.
The point here is that we need a better example project than Pet Store, and I’m sick of having to develop sample projects in document. (“In this example project, we’re tracking Baseball Players and grouping them in Teams. The data objects are in the XYZ package….”)
There are as many options here as there are technologies and audiences, but here is a strategy that has worked for me:
1. Choose an interesting theme which appeals to your customers. If you are working on a NoSQL database, choose something like offline analytics or systems that involve massive graphs of activity (social networking).
2. Develop a “real” application. Don’t just cobble together some contrived application to process thin-air. Think about a real problem that needs solving, and solve it in the context of the technology your are writing about. Make the example open source and choose a very liberal license (BSD-style).
3. Identify a simple subset of the larger application and craft your introductory material around this limited example.
4. As your book or content delves into more complex material, expand the coverage of your example project in your documentation.
In other words, admit that your quickstart documentation has to be constructed around an extremely trivial example and write it in a way that doesn’t require the reader to invest a lot of time in understanding your example. As the reader moves on to more advanced material, you can assume that they’ve passed a critical level of commitment. If they want to fully understand the more complex options for replication, you can ask them to take five minutes to clone an example from GitHub and create a sample database.