This is an update of a post that originally appeared on April 4, 2011.
One of the biggest conundrums for the technical writer is how to handle source code in a book. The goal is to present an easily understood example to the reader—one that demonstrates a principle in a clear and concise manner. In fact, complexity is a problem with many examples—the author tries to stuff too much information into the example and ends up obfuscating the very principles that the reader is supposed to obtain.
There is also the problem with pages because books have a limited number of them. The technical writer must balance the depth and functionality of the examples against a need to present as many examples as possible. Even if a book is balanced, some readers are going to be disappointed that the book doesn’t contain the example they actually needed. So, very often simplicity must win the day in creating application source code for a book, despite the desire of the author to present something more real world, something with additional glitz and polish.
Because the goal of an example is to teach, very often the examples you see in a book have more comments than those that you see in real life. An example in a book must include as much information as possible if the code is going to fulfill its purpose. Of course, book comments should illustrate all the best principles of creating comments in real code. In short, if real world code looked a bit more like book code, then its possible that developers would spend far less time trying to figure code out and more time making changes.
Some readers will take the author to task because the code may not always provide the error trapping that production code provides. In fact, as with many teaching environments, the safety features in code are often removed for the sake of clarity. This problem plagues other environments too. In the past, it was common for woodworking magazines post a note near the beginning of the magazine telling the reader that the safety devices have been removed for the sake of clarity and that no one in their right mind would actually work with woodworking equipment without the safety devices. Likewise, the code you see in a book often lacks sufficient error trapping, making the principle that the code demonstrates clearer, at the cost of fragility. You can usually cause book examples to break easily, but no one in their right mind would create production code like that.
Choosing good examples for a book is hard, so getting your input really is important. I may not be able to provide precisely the example you need or want, but I may be able to provide something similar in the next edition of the book. Of course, I won’t know your needs or wants unless you tell me about them. I’m always open to hearing your ideas. However, I’m not open to providing free consulting in the form of troubleshooting your error code unless you’re willing to hire me to do so. Please keep the discussion to ideas that you’d like to see in book updates by contacting me at [email protected].
