Writing – Page 8 – John's Random Thoughts and Discussions

The Effects of Using Terminology Incorrectly

I read an interesting article the other day by Lorinda Brandon entitled, “When Buzzwords and Jargon Backfire.” The actual article is about the relevance of terms when applied to APIs. However, in a larger sense, the author of the article is spot on in decrying a situation that has continued to occur as long as I’ve been writing (quite a while). People who are involved in an industry, but don’t necessarily understand it completely, misapply terminology related to that industry in a way that causes the terms to lose meaning and focus. In this particular case, the author begs people using certain terminology to explain precisely what they mean and how the resulting infrastructure will benefit the people using it. This is a valid request and one I hope the article’s readers will respect.

However, the article brings to mind far more serious misuses of terminology. Many people still don’t understand the difference between a hacker (someone who understands and uses technology at a low level to perform useful and usually positive tasks) and a cracker (someone who uses technology, not necessarily at a low level, to break into systems and cause other forms of mischief). As an author who really does care about the misuse of terminology, I often try to explain the difference, but as someone astutely pointed out, I’m probably bailing a sinking boat that has a rather large hole in the bottom. In some cases, the terminology is used incorrectly for so long that it acquires a new meaning. Of course, languages change as does every other living thing, so growth in the form of existing words with new meanings and the addition of entirely new words is both expected and encouraged. Someday I may actually give up trying to distinguish between hacker and cracker (but it won’t be today).

However, misusing technical terms doesn’t simply affect the growth of our language. Unfortunately, misusing terms can lead to all sorts of negative consequences—some dire. Imagine that someone has made claims for a particular technology and misused terminology to do so. You may obtain the technology with certain expectations based on the precise definition of the terminology, but only later find that the technology doesn’t address the need at all. What if that technology is used in the health care industry or as part of heavy construction? The misuse of terminology through ignorance or (worse yet) to sell product isn’t acceptable. In most cases, materials written by less skilled authors should be vetted by those who have a firm grasp of the required terminology before the material is released to the public to avoid misinterpretation. It’s a simple, yet effective, means of retaining the meaning of special words.

When writing documents of any sort, keeping a dictionary close at hand and consulting with others who understand terminology at a precise level is always a good idea. It may surprise you to know that I still use these two techniques to ensure my writing is as accurate as possible. I don’t always succeed and you can be certain that some readers will take me to task for my mistakes. Unlike many authors, I do try to clear up these misunderstandings through my blog posts (which I hope that you read). What terminology do you find most confusing? Which terms do you wish others would use with greater precision? Let me know at [email protected].

Defining the Benefits of Failure

In a society that values success above anything else, it seems a bit odd to talk about one’s failures as being beneficial. Even so, failure is beneficial because it helps define what is possible and what is not. Failure helps shape the expectations of those who experience and use it in a positive way to produce a better result the next time. In fact, failure is the greatest teacher of all and something to be embraced rather than shunned. Of course, this sounds quite counterintuitive and perhaps even a bit bizarre, but it’s a fact. All true success comes through a path strewn with failure.

When you consider the role of a technical writer, part of that role is to fail. Readers pay me to play with various technologies—to try to perform various tasks using a variety of techniques. When I find something that works, it’s time to put it into words that the reader can understand and absorb quickly. Failures almost never appear in books except in the form of Notes, Tips, and Warnings (just in case you wondering about the sources of those bits of text). A technical writer fails until a success is achieved and then documents the success so the reader need not fail. So, when you think about it, at least part of the requirement for my occupation is the ability to fail gracefully and to keep trying until a success is achieved.

Failure has even shaped my writing and the techniques employed to produce useful books. Previous posts such as, Methods of Learning and Developing the Reader Profile, are based on failures to communicate in my earliest books. Discovering these techniques and how to apply them specifically to computer texts is an example of failure applied to produce a positive result. Of course, my technique continually evolves as I learn more through my failures.

There are many professions where failure is essential, even mandatory. For example, scientists fail constantly. In fact, Thomas Edison is reputed to have failed around 1,000 times when inventing the lightbulb. Of course, Edison turned the whole idea of failure around and simply stated that he had found 1,000 ways not to make a lightbulb. Even so, he failed. However, it’s important not to miss the significance of the failures. People actually paid Edison to fail when you think about it. They realized that he had the expertise required to eventually succeed and that the failures were simply the road to that success. The people who believed in Edison took his failures in stride, much as the man himself did.

It may surprise you to discover that many of the greatest people in history were equally robust in their failures. Abraham Lincoln is often viewed as our greatest president, and for good reason, his record speaks for itself. Yet, his record is replete with an astonishing number of failures. Viewing the record and then viewing the man makes you wonder whether Lincoln would have ultimately succeeded without that incredible list of failures.

Marie Curie also experienced more than a few failures, yet everyone knows about her because of the successes garnered after working incredibly hard to overcome obstacles that would send most people reeling. Without her work, we might not have many of the medical and other scientific advances we take for granted today. It was failure that shaped Curie, but we focus on the end of the path—the ultimate success of her experiments.

The list of famous failures goes on and I can’t even begin to scratch the surface of that list in this post. The point is that failure, not success, is the teacher of us all. Success is simply the conclusion to any particular course of education by failure. Because of my unique view of failure, it concerns me that our society has taken a course that values success over failure and uses every method possible to avoid it. Our children are taught that they’ll succeed no matter what, that failure is best avoided. The overemphasis on success to avoid the potential pain of failure is seriously hurting everyone and reduces the chance of success in the future. Failure, discover it—embrace it. What is your view of failure. Let me know at [email protected].

Piracy and the Reader

There are many articles written about the effects of piracy—the stealing of intellectual property—on artists and the businesses that work with them. The situation has gotten so out of hand that some people don’t even realize they’re stealing anything. I’ve talked with any number of people who admit to using a free copy of one of my books. When I point out that neither my publisher nor I have issued free copies of anything, they look a bit surprised. After all, why would Joe or Sally give them stolen property, or why would a Web site say material is free when it actually isn’t? It’s human nature to attempt to get everything for the lowest possible price, with free being the best price of all. Some people even think it’s simply wrong to pay for intellectual material; that it should be freely available to everyone. The reason products such as books have been successful so far is that the source of the material has been controlled through the use of paper media. The Internet has changed all that. As described in “Authors and Book Piracy” the losses from piracy to content owners are immense—on the order of $58 billion every year.

I was recently pointed to an article entitled, “The Slow Death of the American Author” by several people. In this case, we’re not talking about outright theft of intellectual property. The party in question is importing foreign copies of books and reselling them to students over eBay at a reduced cost. Foreign editions of books often sell for less for simple reasons, such as the use of lower quality materials and sweat shop labor. In some cases, it boils down to the domestic publisher not having a presence in that country and making a deal with a publisher in another country to distribute the book there at a reduced cost in order to make the book more widely available, but with the limitation that distribution will be kept to that country. There are also situations where a foreign entity has simply stolen the book content and printed copies without paying anyone. The point is that these foreign editions usually end up putting little or no money in the pocket of the author that produced the work and the author is already hard pressed to earn a living from domestic sales.

These and other stories simply point out what we have all known for a long time—eventually it will become impossible for artists of all stripes, including authors of technical books, to make a living through the expression of their artistic skill given the current environment. Of course, I’ll continue to write, as will many other people, but what does this change in the business environment really mean to the reader? No one has really thought about it. At least, I haven’t read any articles by anyone who has contemplated what happens to the people who consume intellectual property as part of their daily lives when the quantity or quality of that material is reduced because the practitioner of the required art must do something different in order to eat.

For some artists, such as musicians, it means a change in business plan. Many more musicians look to concerts or other activities to make a living today given that their recorded music earnings have dropped dramatically. A few artists, such as painters and sculptors, are pretty much unaffected by digital media and will continue working as before. However, for authors such as myself, it may mean a change in occupation. My technical writing could go from something I do for a living to something I do for pleasure when I have leisure time (which probably won’t be very often). There will likely be people who will continue to have leisure time to write, but the overall effect of piracy will be a reduction in both quality and quantity of material available to readers in technical fields. Technical writing pays poorly. The people who actually have the knowledge required to do a good job usually have far better things to do with their time than to write material that someone else will simply steal.

I’m actually looking at a number of ways to stay in business—much as smart musicians have done. What will likely occur in my case is that I’ll find a new way to present my ideas in a form that isn’t quite so easy to pirate or uses piracy in some way to actually earn money. You may see my site filled with ads, for example, or I may put a stronger emphasis on new ways of presenting information, such as interactive books. The idea is that I’m looking for ways to get around the whole issue of piracy because I know there is no way to put the genie back into the bottle at this point and no amount of legislation will cause people to change their basic nature. However, I do appreciate any support you can provide in the meantime through the purchase of my books from locations such as Amazon and by not sharing your digital copies with others.

Of course, I’m always looking for your input. If you have read my blog for a while, you know that I’m in this business because I genuinely enjoy helping others, so it’s important to me to continue serving your needs in whatever way I can. I have already received a few interesting ideas from readers on how to turn this whole situation around, but I can always use more. Given that the publishing industry is slowly dying and that I must somehow continue to pay my bills, how would you approach the problem? Let me know your ideas at [email protected].

Procedures in Technical Writing

A great technical book contains all sorts of content types because different readers learn in various ways. If everyone learned in the same way, technical books would be easier to write, albeit, a bit boring. Procedures are part of the hands-on content that turns a “how” book into a “how to” book. A how book simply shows how something is done. For example, you might see a coding example that shows how to perform a technique. However, unless you actually work with that technique, it’s unlikely that you’ll truly grasp the methodology behind it.

Writing good procedures that actually work is hard. I think the point was driven home to me at an early age by a teacher who seemed to have way too much fun in class. I learned quite a bit from her simply because she made learning fun. When it came time to write a procedure, she chose making toast, which seems to be a typical example. However, when it came time to check our procedure, we each handed our papers to another student who read them aloud while the instructor performed the steps precisely as written. Many of us forgot to mention taking the bread out of the wrapper, so she’d politely try to stuff the pieces, wrapping and all, into the toaster. It was a hoot, but also a great lesson.

All authors have an issue with assuming that the person viewing the procedure knows something that doesn’t appear in the write-up. The person ends up trying to stuff the bread into the toaster without taking it out of the wrapper first. Even though the example was quite humorous in that teacher’s classroom, in real life the omission of important material is frustrating for everyone because the author truly doesn’t understand why the reader is having a problem with the procedure. I’ve gone through the process myself—many times. As I’ve matured as an author, I’ve come to realize that I need to draw the answer to the problem with my procedure out of the reader without getting the reader any more frustrated than he or she is at the moment.

Good procedures, like good newspaper articles, answer who, what, where, when, why, and how. Even that requirement seems counterintuitive. Most authors seem quite pleased when they can accomplish the “how” part of the equation. The who part of the equation is often the hardest part of the procedure. Who is performing the task? It seems like an easy question to answer, but often I need to go back through a procedure and decide who is doing what and at what time. Doing something at the wrong time is often just as bad as not doing it at all. The question of where comes into play because modern computer systems have applications that interact with each other. Deciding where the person performing the procedure is at any given moment is essential to making the procedure work as expected.

Of all the questions though, the question of why is the easiest to answer, yet the most often missed. If a person does something like an automaton, there is no feeling of accomplishment—no sense of gratification. The reader goes through the motions without understanding anything about the procedure. As a result, the information doesn’t sink in and the reader is reduced to using the procedure precisely as written to perform only the task the procedure is designed to address. The best procedures answer the question of why so that the reader can use the procedure in various ways to address a wide range of problems that the author hadn’t even considered when writing the procedure.

Procedures are important. As a hands-on tool for interacting with the user, procedures present the opportunity for the author to extend the meaningful use of a book well beyond its intended purpose. An author truly can’t aspire to do more than that! Let me know your thoughts on writing procedures at [email protected].

E-book Integration in Schools

I use every opportunity I can to track the change in how people read information. Some of this material is in articles, some comes from readers and friends, and some comes from just observing. For example, at one time people would grab a magazine from the rack at our doctor’s office. Now it’s quite likely that they’ll take out a Kindle or other reading device to view their favorite novel. Even at our library, I see people sitting in front of computers reading, rather than holding a book. Increasingly, I get questions from readers who use the e-book version of my books, instead of paper copies. Let’s just say that in the year and two months since I wrote The e-Book in Your Future, things have changed considerably. E-books are reducing the cost of reading material of every sort, especially technical books.

That’s the reason I’m a bit concerned about some of the things I read about our school system, especially when conversations with students tend to bear out the information I read. One ComputerWorld article in particular, “The e-book revolution is bypassing U.S. elementary schools” really grabbed my attention. The author, Joe Mohen, makes some astute comments about the benefits of using e-books in schools. As an author, I see significant benefits in using e-books, such as the ability to update the information as needed. Schools often struggle with outdated texts now due to a lack of funds, using e-books greatly reduces the cost of updates making it possible for schools to keep their texts updated.

More worrisome is the fact that most of our colleges still use paper texts. In talking with any number of students, I have yet to find any of them using more than one or two e-books for their classes. Given the high cost of education, it makes sense to reduce costs by providing students with materials in electronic format. A recent Forbes article, “Should College Students Be Forced To Buy E-Books?” makes a strong case for using e-books in colleges. The same article points out that only three percent of students currently use e-books for their education.

My interest in e-book technology isn’t just a passing fancy. Part of the reason I spend so much time delving into this issue is to discover how to serve you best. A large percentage of my readers are college students. What if my books were offered only in e-book format? Would you still buy them? For now, my books will continue to appear in both print and e-book format for the most part, but the time could come when I’m asked about how my readers would be affected if the publisher produced only e-books. To answer that question, I need your input. Let me know your thoughts about e-books, especially in the school environment, at [email protected].

Sending Comments and Asking Questions

Anyone who reads my blog for very long understands that supporting my books is a big deal for me. I actively work with my readers because I realize that you have the choice of using books written by other authors. Let’s just say that my support system is one of the reasons you really do want to buy my books. My blog not only answers common questions you have, but also adds examples and other information to the information you already receive through my books, so make sure you keep you eyes peeled for additional information here as well.

The last time I discussed this topic was in 2011 in my Contact Me, Please! post. The same things apply now as they did then. I’ll answer your book-specific questions as soon as I possibly can and in as much detail as I can. However, I won’t write your school term paper for you, accept a marriage proposal, or provide free consulting (amongst other things readers have asked me to do in the past). If you’re having problems with an example or can’t find the book’s source code, please be sure to ask because I want your experience with my books to be nothing less than phenomenal.

I also encourage you to be a beta reader. You can see the posts I’ve made for several recent books. The biggest reason for me to ask readers to participate in the book building process is to ensure you get the book you want. I also want to avoid Errors in Writing. As far as I know, I’m the only technical author on the planet that invites reader comment during the writing process, but I truly feel your input is essential, so I request it in every way I can. As I get new book contracts, you’ll continue to see requests for beta readers posted on my blog.

You can always contact me at [email protected] with any comments and questions you have. This includes both books and blog posts. Let me know about any concerns you might have and I’ll do my best to solve them. In the meantime, happy reading !

Too Much Detail

A trend has started in publishing of all sorts and it affects technical writing most of all. A friend of mine recently wrote a piece entitled, “A Multimedia Avalanche.” The post spoke to me on many different levels. As an author, it spoke to me of the need to keep my pieces short and to the point. No one wants to read every detail about every event that has ever happened—it simply isn’t possible to absorb more than the “Reader’s Digest” version of many of the events that take place in our lives. It makes me think of the supposed Sergeant Friday (Dragnet) quote, “Just the facts, ma’am.” The problem with using a medium such as the Internet is that people tend to think in terms of unlimited space, rather than limited reader attention. As an author, it’s important to write concisely, yet clearly.

As a reader, it spoke to my desire to throttle some authors to within an inch of their lives. After wasting my time, they never do seem to get to the point. An editor of mine is famous for pointing to the need to state the purpose of an article within the first paragraph and then to keep the article focused on that purpose. It’s good writing practice to write the beginning and ending of the article first, and then write the material needed to fill in the details. It’s a simple trick to keep the article short and focused.

As a citizen, the article spoke to the need to keep the media in check. No, the government shouldn’t perform this task; the reader should. When the media hypes a story all out of proportion, it brings out the mob mentality of some people. Suddenly, the government finds itself swamped with calls for needless changes for a non-event that was sensationalized by someone who wasn’t thinking. These sorts of issues tend to waste considerable funds that could be better used for other purposes (such as saving the taxpayer from an increase in taxes).

Information overload, wasted money, wasted time, and other such problems will only increase as citizen journalists and others with way too much time on their hands contribute toward an increasing array of articles that bury the reader in detail. To quote my friend’s article, “just because you can do something doesn’t always mean you should.” It’s good advice.

What is your take on too much detail, especially as it relates to technical writing? Let me know your thoughts at [email protected].

Winter Feathers

Feathers on my window pane,
Tell me winter’s here again.
Elfin hands paint lines at night,
That morning’s sun, shows so bright.

Though the feathers look like glass,
With winter’s sun they cannot last.
Like a dream they fade away,
‘Til nothing’s left in the day.

Come the night they reappear,
As the sun does disappear.
Each cycle brings to my view,
Winter feathers always new.

Writing the Introduction and Summary

I read a lot of books in a year. In fact, it’s not unusual for me to read a book or two every month of the year. While it may take three or more months to read something for pleasure, such as a favorite fantasy novel, technical books usually receive my intense interest for less than a month. Once I pick it up, I’ll keep reading until I’ve finished the book. Unlike many readers, I do read technical books end-to-end so that I can pick up new writing techniques, as well as information. When it comes to technical books, I’ve found that there are usually two flaws that make me scratch my head: the introduction and summary.

The introduction is akin to an advertisement or possibly an invitation. You want to provide a reader with a good reason for viewing the material. After all, the reader’s time is precious and there are many authors on the market peddling their wares. An invitation to read a particular chapter is not only necessary, it’s essential if you want the reader to spend time with the book. A good introduction highlights the reasons why the reader should continue and tempts the reader with the fine fare you’ve diligently created. However, introductions should also be short. You have about 30 seconds to convince someone to read a chapter—possibly less in this day of the sound bite. Instead of focusing on the question of what, the author should tell the reader why. It’s important to say why the reader should read the chapter and describe how much the reader stands to gain by doing so.

Summaries are eschewed by most readers for good reason—they’re boring. In many cases, it’s obvious the author didn’t devote much thought to the summary, so it isn’t hard to figure out why the reader doesn’t devote any time to it. Over the years, I’ve stopped calling the end of the chapter a summary because the term has picked up such a terrible meaning. Rather, I use a heading that at least promises to excite the reader a little. My summaries do tend to follow a formula that I modify as needed to satisfy the requirements of the target reader for my book. I write three or four paragraphs that answer these questions:

What is the most important bit of information the reader can take away from the chapter?
Now that the reader has new information, how can the reader apply it in a specific way?
How does the next chapter expand on the content of this chapter (or what new topic does it cover)?

In working with the introduction and summary, I’m careful not to develop new information. I simply direct the information I cover in the body of the chapter in a specific way. Yes, the summary does imply new information in the form of a call to action, but the call to action is not the topic I’m discussing, but rather invites to the reader to apply what the chapter has taught in order to make the lessons more permanent.

The content of the introduction and summary does vary by publisher. Specific series have specific requirements and I always do my best to make use of these requirements in a way that helps the reader obtain the most from that particular chapter. In addition, beta readers have often requested that I include some special feature in either the introduction or summary to help make the chapter more useful. I listen to these comments carefully because the beta readers probably know better than I do what will attract another reader’s attention.

Summaries can be especially hard. There are times where I’ll rework a summary several times to get the effect I want. In some cases, my summaries will include questions or other special features because simply telling the reader to go out and use the information learned seems inadequate to address the topic at hand. No matter how you write your introductions and summaries though, you do need to treat them as an important part of the chapter. The first invites the reader into the chapter and the other bids the reader adieu. Both provide the reader with a lasting impression of your skill as an author and both change the way the reader views the content of the rest of the chapter.

What is your reaction to technical book introductions and summaries? Do you often feel as I do, that they are simply bolted on as a means to start and end the chapter, but not much else? What would you like to see in an introduction or summary? Let me know your thoughts on the topic at [email protected].

S	M	T	W	T	F	S
					1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30