IDE Screenshot Usage in Books

There are cases where it’s very tough to figure out the correct presentation of material in a book, which is made more difficult by some readers preferring one presentation and other readers another. It comes down to how people learn in many cases. Visual learners prefer screenshots, abstract learners prefer text. Of course, there are all sorts of learners between these two extremes. So, what seems like a simple question can become quite complex.

The question at hand is whether to present screenshots of an IDE in a book with the associated example code and its output. The problem is that vendors now assume that developers have very large displays and so have made use of all of that extra screen real estate. In addition, book publishers don’t want books where a single image consumes an entire page. The result is that it’s very hard to get a screenshot where the text is completely readable. It can be done, but the text will generally still be smaller than the print in the book. Older readers complain that they need a magnifying glass to see the text at all.

However, there are benefits to using screenshots. The most important benefit is that, even if the text isn’t completely readable, visual learners can see what their IDE should look like as they follow the progress of procedures in the book. This feedback lets the visual learner know that they are doing things correctly and are getting the correct result. Another benefit is that an example tends to stay in one piece. The graphical output of an example doesn’t end up several pages away from the source code that produces it. Sometimes, textual output is wider than the page will allow using the normal font size. So, the options are to print the output in the book at the normal font size, but in a truncated form, which means that it’s no longer complete. A screenshot can show the complete textual output, but at a smaller font. For beginner readers, the second form, while not optimal, is preferred because truncating the output produces questions in the reader’s mind.

So, how do you feel about IDE screenshots in books? Are they more helpful or more confusing? Part of the reason for posts like this is to get your opinion and discover more about you as a reader. Obviously, a book author wants to use the communication techniques that work best overall for everyone, book space often not allowing for the investigation of every presentation alternative. Let me know your thoughts at [email protected].

Ongoing Education

This is an update of a post that originally appeared on April 7, 2011.

In looking at a lot of my previous posts, I try to see the truth value in them. Did they hold up to the test of time? When it comes to ongoing education, it doesn’t matter how old you get, you still need to learn new things. I encountered a friend at the library the other day, long retired, he’s still feeding his brain with new things and doing so makes him a very interesting person to talk to.

There are only 24 hours in each day, making it impossible for any one human to know the sum of human knowledge or even a small portion of it. The 24 hour limit means we must actually choose carefully and depend on others to have knowledge we don’t possess. Anything that isn’t growing is dead and a form of growth is the increase of both knowledge and wisdom.

Of course, I do obtain daily increases in knowledge. The art of writing technical books is embracing a strategy of learning all the time. I read voraciously, subscribe to word builders, and conduct experiments to see just how things really work (as contrasted to the theoretical discussions in the books and magazines I read). The very act of writing involves learning something new as I discover new ways to express myself in writing and convey information to readers. I’ve picked up books I wrote early in my career and am often appalled at what I considered good writing at the time, but it was good writing given my experience, even though it would be unacceptable today.

Learning is part of every activity in my life and I relish every learning event. So it was on this particular weekend twelve years ago that my wife and I packed our lunch and sent to Get Ready…Get Set…Garden! We looked forward to it every year. This year we took classes on hostas (for fun) and horseradish (as part of our self-sufficiency).

Before we went to class though, we just had to spend a little time looking at some of the displays. A personal favorite of mine was the gourds:

A display of interesting things made with gourds.
A display of interesting things made with gourds.

I’ve always wanted to make some bird houses, but never quite have the time. They actually had a class on the topic this year and I was tempted to take it, but that would have meant missing out on the horseradish class, which I considered more important. Here’s Rebecca and me standing in front of one of the displays:

John and Rebecca standing in front of one of the displays.
John and Rebecca standing in front of one of the displays.

Well, onto the classes. I found out that there are over 2,000 varieties of hostas, which I found amazing. They originated in Japan, Korea, and China.  It takes five years on average to grow a hosta to full size, but it can take anywhere from three years to ten years depending on the variety. I found out our place for growing them is perfect, but our watering technique probably isn’t, so we’ll spend a little more time watering them this summer. Our presenter went on to discuss techniques for dealing with slugs and quite a few other pests. Most important for me is that I saw some detailed pictures of 50 of the more popular varieties that are easy to get in this area. I’ll be digging out some of the old hostas in my garden and planting new as time allows.

The horseradish session was extremely helpful. I learned an entirely new way to grow horseradish that involves laying the plant on its side for the first six weeks, digging it up partially, removing the suckers, and then reburying it. The result is to get a far bigger root that’s a lot easier to grind into food. I can’t wait to try it out. Of course, our instructor had us sample a number of horseradish dishes while we talked. I’m not sure my breath was all that pleasant when we were finished, but I enjoyed the tasty treats immensely.

So, what are your educational experiences like? Do you grow every day? Let me know at [email protected].

Using Notes, Tips, and Warnings Effectively

This is an update of a post that originally appeared on March 18, 2016.

Writing is all about emotion—I’ve mentioned this need quite a few times in the past. There are many ways to create emotion in technical writing. Of course, word choice, sentence structure, and other tools of the trade come into play, just as they do for every other form of writing. However, one of the approaches that is truly different in technical writing is the use of notes, tips, and warnings. In all three cases, you create a single paragraph sidebar-like structure, but the emphasis and nuance of the inclusion is different from other sorts of writing:

  • Notes: Information that you want to include as an aside to the main text. You might choose to document the information source, the location of additional information, or augment parts of the main text in some way. The emotional impact of a note is the feeling of being special. When the reader sees a note, it should evoke a feeling that this is peculiar or extraordinary information that could impact the reader’s use of technology.
  • Tips: Information that is extra in nature. You might choose to include a personal technique that you haven’t seen documented anywhere else, the location of goodies that won’t necessarily affect the reader’s use of technology described in the book, but will add to the readers appreciation of that technology, or some sort of gift-like source, perhaps a free download. The emotional impact of a tip is one of surprise. When a reader sees a tip, it should evoke a sense of getting extra value from the book—something unexpected that adds value to the reading experience. A reader should get the tingly feeling that one gets when receiving an unexpected present.
  • Warnings: Information that is dire in nature. Reserve warnings for those times when a reader’s incorrect action could cause personal, data, or other sorts of damage. The emotional impact of the warning is dread. The reader should see a warning as a notification that incorrect actions are rewarded negatively—they’re the stick that goes with the carrot of notes and tips.

It’s important to remember that these three constructs aren’t the main event. Your body text is still the main event and these three elements serve only to emphasize that material in some way. Depending on the book you write, you may have other specialized paragraphs at your disposal. Each of these unique paragraph types should evoke a particular emotion. Unfortunately, the emotion they should evoke is seldom documented, so you need to figure it out for yourself. It’s essential that you do take the time to discover what emotion the paragraph is supposed to evoke (or simply not use the special paragraph in your writing).

Keep notes of what you do and why you do it. When working with various kinds of special writing, you want to be sure that the emotions you evoke with unique paragraph types is consistent across your various publications, especially if those publications are all from the same publisher. Create a style guide of a sort for yourself that contains these notes to yourself so that you can find them easily. Organizing your style guide for easy access is also a plus (which means your style guide should appear in digital, rather than paper, format.

Unlike sidebars, notes, tips, and warnings are rarely more than a paragraph long. You could possibly make an argument for two paragraphs in rare circumstances. The paragraph should contain two or three sentences with the first sentence providing a summary and the second providing details. A third sentence provides ancillary information as needed. The structure and content of your special paragraph should reflect the kind of paragraph you’re creating—as with a good actor, keep your paragraph in character. After all, it’s a performer on the stage of your book and presents the reader with a special feature that is unavailable elsewhere.

Using the special paragraphs at your disposal in the correct way can mean the difference between communicating effectively with your reader and losing the reader’s attention completely. Let me know your thoughts about the use of notes, tips, warnings, and other special paragraphs at [email protected].