Handling Source Code in Books

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 readerone that demonstrates a principle in a clear and concise manner. In fact, complexity is a problem with many examplesthe author tries to stuff too much information into the example and ends up obfuscating the very principles that the reader is supposed to obtain. 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. All of my 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 good 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.

The feature that I’ve constantly worked on with the code in my books is accessibility. In as much as possible, the code demonstrates how to make an application usable by those with special needs. Of course, as with the exception handling, it isn’t always possible to add all of the required accessibility features without making the code less clear. Still, I’m a strong advocate of making code completely accessible whenever possible.

Readers will likely question just how useful book code is if it leaves safety and accessibility features out. Remember that the goal is to teach. Let me know your thoughts about source code in books at John@JohnMuellerBooks.com.

 

Errors in Writing

I get upwards of 65 e-mails about my books on most days. Some of the conversations I have with readers are amazing and many readers have continued to write me for years. It’s gratifying to know that my books are helping people—it’s the reason I continue writing. Although I make a living from writing, I could easily make more money doing just about anything else. The thought that I might help someone do something special is why I stay in this business. When I actually hear about some bit of information that has really helped someone, it makes my day. I just can’t get the smile off my face afterward.

Of course, I’m constantly striving to improve my writing and I do everything I can to help the editors that work with me do a better job too. Good editors are the author’s friend and keep him from looking like an idiot to the reading public. In fact, it’s the search for better ways to accomplish tasks that has led me to create the beta reader program. Essentially, a beta reader is someone who reads my books as I write them and provides feedback. The extra pair of eyes can make a big difference. Beta readers who provide constructive feedback on at least three chapters receive my thanks in the book’s Acknowledgments and a free copy of the published book. (If you’d like to be a beta reader, please contact me at John@JohnMuellerBooks.com for additional details.)

You’d think that with all the pairs of eyes looking at my books, they’d come out error free. After all, it isn’t just me looking at the book, but several editors and the beta readers as well. Unfortunate as it might seem, my books still come out with an error or two in them. The more technical the topic, the greater the opportunity for errors to creep in. Naturally, the errors are amazingly easy for just about everyone else to pick up! (I must admit to asking myself how I could have missed something so utterly obvious.) When there is an error found in the book, I’ll provide the information to the publisher so it’s fixed in the next printing. The error will also appear on the book’s errata page on the publisher’s site. If the error is significant enough, I’ll blog about it as well. In short, I want you to have a good reading experience so I’ll do everything I can to hunt the errors down and correct them.

However, not every seeming error is actually an error. There are times where an apparent error is simply a difference of opinion or possibly a configuration difference between my system and the reader’s system. I’ll still try to figure these errors out, but I can’t always guarantee that I’ll fix things in your favor. After all, another reader has probably found still other results or has yet another opinion on how I should present material in the book.

The long and short of things is that despite my best efforts, you’ll probably encounter an error or two in my books and I apologize for them in advance. We’ll also continue have differences of opinion and that’s usually the source for new ideas and new ways of viewing things. I’m honest enough to admit that I do need your help in creating better books, so I’ll always listen to you and think about what you have to say. I hope that you’ll continue to read my books and do amazing things with the information you find therein. The results of your researches are truly the reason I remain in this business and I realize that we’re in this together. Thanks for your continued support!

 

Is E-mail Dead?

I keep reading articles that tell me that e-mail is dead. In fact, there was one today on ComputerWorld that describes a company that is moving from e-mail to social media as an exclusive option. Currently, I don’t use any of the options mentioned in the article and don’t have time (or the inclination) to start using them. Don’t get me wrong, social media probably solves problems for some part of the population, it just hasn’t worked out well for me. I can’t see myself outputting tweets about my daily activities and some of the articled I read about Facebook are just plain scary.

My main problem with most modern communication solutions is that they’re overly intrusive. I was in the bathroom the other day and a guy was engaging in business while sitting on the commode; he just couldn’t be bothered to turn his cellphone off to take care of personal matters. That’s just one of many scenarios I’d prefer to avoid. There is strong evidence to conclude that our society has become preoccupied with communication, to the detriment of all. Just how many people died last year from texting accidents? According to the Washington Post, 28 percent of accidents now occur while people are texting or talking on a cellphone. I’m pretty sure I don’t want to talk with someone that badly.

I have to wonder how well social media will work for business needs. Social media assumes a level of connectivity that I’m simply not willing to allow. E-mail works better because someone can send me a message and I can handle it later; at my convenience. More importantly, I can handle the e-mail at a time when I’m not distracted by something else. In addition, I can provide a thoughtful answer; one that I’ve researched and thought through carefully. E-mail also provides me with a permanent written record that I can reference later when I have questions about the discussion.

There is some evidence to say that social media is actually costing business big dollars. For example, the BBC claims that social media is costing business £1.4bn. Other articles are equally certain that social media can save businesses money. I’d say it would be pretty tough to come up with a precise statement either pro or con when it comes to social media’s cost to business, but I know the personal cost. I tried a few solutions as an experiment and found that I was considerably less productive using them than turning it all off and using e-mail. Of course, that’s me, you may very well find that using social media makes you more productive; each person is different.

Personally, I don’t see e-mail as a dead communication technology. If anything, it’s becoming more important to me as I age and my memory becomes less dependable. As far as I’m concerned, the always connected nature of most social media today simply isn’t a good solution if you want to be productive. So, what’s your take on social media? Let me know at John@JohnMuellerBooks.com.

Paper or e-Book?

I’ve been thinking about something for quite a while now. For me, there is nothing better than sitting by my wood stove, coffee cup next to me, reading a favorite book. Of course, I’m talking about a hard cover or paperback book. Nothing quite matches the feel and smell of paper, especially when you’re reading a book for leisure. The hours I’ve spent reading books have been pleasurable to the extreme. I’m transported to worlds of mystery in some cases, worlds of the future in others. Fantasy, science fiction, techno-thriller; they all hold a certain thrill.

It’s a different matter when I start working with technical material. As you might imagine, I’ve collected quite a few technical books in 23 years. In fact, I’ve discarded quite a few books during that time; a mountain of technical knowledge that no longer seems important to anyone but a historian. That is, until I figure out that I discarded the one antique I really did need for a particular project. Suddenly I’m looking somewhere, anywhere, for that book. Even when I know where the book resides and I peruse its well thumbed pages by instinct, finding just the right information can prove difficult.

Unfortunately, no book cataloging system in the world will solve my problem. I could catalog each of my hundreds of books and still not find the information I actually need with any speed. Of course, the ability search quickly is one of the benefits of electronic storage. If I had my books in electronic format, I might avoid the hours upon hours of search time for that one piece of information I actually need. Then again, I’ve accidentally found many pieces of useful subsidiary information during such searches, so it’s not possible to discount paper as unworthy. Still, speed is of the essence while I’m working on my next project.

For now, it appears that my future will rely on two media for books: paper for leisure and electronic for work related materials. It’s a sad thing for me to admit, but the paper book has become a bit too cumbersome for a world where speed is prized above all. What about you? What do you feel about e-books?