Tag: Writing

Apathy, Sympathy, and Empathy in Books

This is an update of a post that originally appeared on May 23, 2016.

I’ve written more than a few times about the role that emotion plays in books, even technical books. Technical books such as Accessibility for Everybody: Understanding the Section 508 Accessibility Requirements and Machine Learning Security Principles are tough to write because they’re packed with emotion. The author not only must convey emotion and evoke emotions in the reader, but explore the emotion behind the writing. In this case, the author’s emotions may actually cause problems with the book content. The writing is tiring because the author experiences emotions in the creation of the text. The roller-coaster of emotions tends to take a toll. Three common emotions that authors experience in the writing of a book and that authors convey to the reader as part of communicating the content are apathy, sympathy, and empathy. These three emotions can play a significant role in the suitability of the book’s content in helping readers discover something new about the people they support, themselves, and even the author.

It’s a mistake to feel apathy toward any technical topic. Writers need to consider the ramifications of the content and how it affects both the reader and the people that the reader serve. For example, during the writing of Artificial Intelligence for Dummies, 2nd Edition, Python for Data Science for Dummies, and Machine Learning for Dummies, 2nd Edition Luca and I discussed the potential issues that automation creates for the people who use it and those who are replaced by it in the job market. Considering how to approach automation in an ethical manner is essential to creating a positive view of the technology that helps people use it for good. Even though apathy is often associated with no emotion at all, people are emotional creatures and apathy often results in an arrogant or narcissistic attitude. Not caring about a topic isn’t an option.

I once worked with an amazing technical editor who told me more than a few times that people don’t want my sympathy. When you look at sympathy in the dictionary, the result of having sympathy toward someone would seem positive, but after more than a few exercises to demonstrate the effects of sympathy on stakeholders with disabilities, I concluded that the technical editor was correct—no one wanted my sympathy. The reason is simple when you think about it. The connotation of sympathy is that you’re on the outside looking in and feel pity for the person struggling to complete a task. Sympathy makes the person who engages in it feel better, but does nothing for the intended recipient except make them feel worse. However, sympathy is still better than apathy because at least you have focused your attention on the person who benefits from the result of your writing efforts.

Empathy is often introduced as a synonym of sympathy, but the connotation and effects of empathy are far different from sympathy. When you feel empathy and convey that emotion in your writing, you are on the inside, with the person you’re writing for, looking out. Putting yourself in the position of the people you want to help is potentially the hardest thing you can do and certainly the most tiring. However, it also does the most good.

Empathy helps you understand that someone who loses a job to automation isn’t looking for a new career, the old one worked just fine. The future doesn’t look bright at all to them. Likewise, some with disabilities isn’t looking for a handout and they don’t want you to perform the task for them. They may, in fact, not feel as if they have a disability at all. It was the realization that using technology to create a level playing field so that the people I wanted to help could help themselves and feel empowered by their actions that opened new vistas for me. The experience has colored every book I’ve written since the first time I came to realize that empathy is the correct emotion to convey and my books all try to convey emotion in a manner that empowers, rather than saps, the strength the my reader and the people my reader serves.

Obviously, a good author has more than three emotions. In fact, the toolbox of emotions that an author carries are nearly limitless and its wise to employ them all as needed. However, these three emotions have a particular role to play and are often misunderstood by authors. Let me know your thoughts on these three emotions or about emotions in general at [email protected].

Handling Source Code in Books

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].

Introducing Machine Learning Security Principles

Are you a manager, researcher, or novice data scientist who works with data regularly, yet can’t really understand the technobabble found in security books that are supposed to help you secure the data you work with? Machine Learning Security Principles is all about providing you with full disclosure of all of the security threats that can affect your data in a detailed way that is also understandable. The idea is to understand the threats and understand the players in the security arena so you can create a strategy that will ensure your data remains safe without feeling completely lost in the language used by most books today.

Machine Learning Security Principles looks at data from every possible perspective, which means that you’ll learn more than just collection and storage methods. It isn’t just the hackers and disgruntled employees that are the problem. You now have to deal with governments that tell you how to collect data properly and face the wrath of the pubic at large when the data is collected in a less than ethical manner, even when no laws have been broken. In addition, it’s more than just the data, it’s also the system that holds the data, the application the uses the data, and the users who enter the data that can become problematic. With this in mind, here are some things that you’ll learn when reading this book:

  • Learn methods to prevent illegal access to your system.
  • Discover detection methods when access does occur.
  • Employ machine learning techniques to determine motivations.
  • Mitigate hacker access using a variety of methods.
  • Repair damage to your data and applications.
  • Use ethical data collection methods to reduce security risks.

A major complaint with most books on the market is that there is an expectation that you’re not only an expert coder, but that all you want is to see code. That’s fine if you’re already a seasoned security expert, but then seasoned security experts really don’t need books like this one. Machine Learning Security Principles provides you with several ways to learn about security issues:

  • References to actual security break-ins and the results of them.
  • Block diagrams showing how various kinds of security issues occur.
  • Explanatory text that helps you understand what precisely can happen and how to prevent.
  • Example code that you can use to discover how various security techniques work.
  • Example data and the techniques you can use to work with it.
  • Resources that you can use to augment your security plan.
  • Online tools you can use to more fully explore security issues.

In short, Machine Learning Security Principles provides you with several methods of learning about security in an easy to use manner. It doesn’t take a one size fits all approach. Please let me know if you have any questions about my new book by contacting me at [email protected].

Get the Source Code for My Books from Another Source

A lot of readers have asked me to provide a better, centralized, location for the source code for my books. With this in mind, I’ve created a new Source Code web page on my website. All you need to do to use it is locate the name of the book whose source code you need and click the associated link or Download button. Not all of my books appear on the Source Code page yet, but I’m working on it. If you find that you can’t locate a book you desperately need, please let me know at [email protected]. I’ll do my best to help you make great use of my books. Please continue to frequent this blog for updates and news about my books.

Writing Involves Reading

A lot of people think that ideas simply come into my head from nowhere and then I write them down. At some point, usually after three or four hours with several coffee breaks thrown in, I go fishing or do something else with my life. Somehow, the books just magically appear on sites such as Amazon and in the bookstores.

Unfortunately, writing isn’t quite that simple. During any given week I probably spend a minimum of 14 hours reading, often times more. I don’t just read computer science books either. In fact, many of my best ideas come from non-computer sources. It’s hard to say what will make a good source for ideas for my particular kind and style of writing. I’ve actually had poems influence me and more than a few fiction books. I once created a section of a chapter based on an idea I got from a Tom Clancy novel. The point is that writers are engaged in two-way communication. We get input from all sorts of sources, use that input to create new ideas and concepts, and then write those new bits of information down for others to read.

Reading differs from research. When an author researches something, the focus is direct and narrow. The goal is to obtain specific information. Reading is far more general. There really isn’t a focus, just communication. In reading a book or magazine, I might find a new technique for presenting information or a perspective I hadn’t considered before. The goal is to obtain experiences; to explore the world of print in an unfettered manner. The result is often enhanced creativity.

Of course, just as no one is able to get up in the morning and say, “Today I will be brilliant!” with any level of serious intent, reading may not produce any lasting effect at all. The communication may be an ephemeral experience of pleasure, joy, or some other emotion. Even in this case, letting the subconscious mind work while keeping the conscious mind entertained is a good idea. Sometimes a reading session, followed by a walk or some other activity, yields a solution to a writing problem that has nothing to do with the reading or the walking, but simply the allocation of time to the needs of the subconscious mind.

The bottom line is that if you want to become a writer, then you really must engage in writing activities because writing is as much about practice as it is talent. However, you must engage in other forms of communication as well or your skills will top out at some level and you’ll never fully realize your potential. Reading is truly a fundamental part of writing. Let me know your thoughts on reading as part of building skills in writing at [email protected].

 

Choosing to Use Graphics

Graphics can be a tricky issue in technical writing. Some authors use graphics at the drop of a hat. Often, the graphic shows something that the reader can readily understand from the text or contains nothing of value to the reader. For example, some books contain images of objects that don’t have any intrinsic value of themselves and possibly contain a little text that the author could easily include in the text. However, some authors err to the other extreme. Some abstract concepts lend themselves to pictorial representation. For example, a block diagram can often convey relationships that would be impossible to describe using text alone. Consequently, the issue of whether to use graphics within a text or not often hinges on the graphic’s ability to convey meaning that words alone can’t.

However, the decision to use graphics often involves more than simply conveying information. The quality of the graphic also matters. Graphics that appear too small in the book make it impossible for readers to make out details and render them useless. Designing a graphic that provides all the required details can be time consuming. However, including a less than useful graphic in the book is generally a waste of space. In some cases, the solution is to provide a reference to an external source (such as the Internet) for the graphic, rather than include the graphic directly in the book. Some authors have a strong desire not to use external sources because they tend to change, but using poorly designed graphics that fail to convey the desired information to most readers is equally problematic.

Focusing the graphic is also a problem. When a graphic contains too much detail or contains elements that have nothing to do with the discussion, the message can become lost. Using a cropped graphic helps focus attention and reduces the amount of space the graphic consumes in the book. By focusing reader attention on specific details, it also becomes easier to convey a specific message. Most important of all, keeping individual graphics small (yet easily readable) is essential to allowing use of as many graphics as is needed for the book as a whole.

The bottom line is that authors who use graphics effectively are able to communicate a great deal of information to readers in a modicum of space. In addition, using graphics presents the reader with another way to learn the material. Many people don’t learn well just by reading text, they also require graphics, hands on activities, exercises, and the like in order to learn a topic well. When choosing to use graphics, you must consider all aspects of how the graphic will appear to the reader. Let me know your thought on graphics usage at [email protected].

 

Developing Good Work Habits

Writing, like any kind of work, requires a certain amount of discipline. However, unlike many sorts of work, pounding away at the keyboard is only helpful when you have ideas to get onto paper (digital in most cases today, but the idea is the same as writing in the past). In order to become more productive, you must develop good work habits. Part of the task is to base your work habits on the kind of writing you do, your personality, and the requirement to get a certain amount of work done in a given time. It’s also important to consider your work environment.

I normally work a 12 to 14 hour work day, but I don’t spend all that time at the keyboard. My work day is split into one hour segments with 15 minute breaks. The day always begins with chores and breakfast for me. After all, everyone has to eat. During my first segment, I’ll answer e-mail, and then it’s usually time to take a break. I get some cleaning done or get the wood stove ready for the evening fire. The point is to get out of the office for 15 minutes so that I can rest, but also remain productive.

I am a huge believer in keeping your work environment clean and tidy. One of my best friends works in an Office and so they have a commercial office cleaning service to take care of their workplace for them. Clutter and dirt can be incredibly distracting and can even prevent you from enjoying your work which can have a detrimental impact on your productivity over time. Contacting cleaning services Red Deer, or ones closer to the office vicinity, will help keep everything together and clean. So whether you work in an office or from home, try to be as tidy as you can. Cleaning is also a great way to take a step away from the screen which is incredibly important for your creativity. Whilst cleaning is important, there will always be some jobs that people are unable to do. For example, cleaning the outside of the windows will be a difficult job for staff to do quickly whilst they’re in the office. This job will normally have to be done by a professional window cleaning company. Ideally, windows should be cleaned regularly, so it’s important that residential and commercial properties consider contacting their local window cleaners.


During the second segment I normally write as much text as I can. Sometimes this means pressing pretty hard in order to get the task done, but you need words on paper to move forward. Last week’s post mentioned some ways in which I get the job done. This segment usually goes by so fast that it seems as if I’m just starting when my timer goes off. Yes, I use a timer on my computer to keep a routine in place. Pacing yourself is important. At the end of the second segment it’s usually time to check the chickens and get any eggs they’ve laid. A walk outside is nice too. Sometimes I play Frisbee with the dogs or do some cleaning or even just enjoy some sunshine while I read the newspaper.

The third segment sees me editing the text I’ve written during the second segment and augmenting it. I usually end up with half again the number of pages that I had at the end of the second segment. The point is that the book has advanced, but that the text is also in better shape by the end of the third segment.

Depending on how everything has gone, I can sometimes fit in a fourth segment that I use to research new book material. I write ideas for the current chapter directly into the remaining blank spots so that I can start working on them immediately after lunch.

Lunch is an hour long. Afterward, I check on the animals again, check out the orchards and gardens as needed, and generally get things cleaned up. You’ll notice I do a lot of little cleaning segments during the day. For me, it’s better than trying to clean the entire house all in one fell swoop. Plus, I like a clean environment in which to work, some people actually do work better in clutter. There isn’t any right or wrong to the question of environment, just what works for you.

The rest of the day goes pretty much like the first part of the day went. I’ll have a robust writing segment after lunch, followed by an editing segment, followed by a research segment. It may seem mundane and potentially quite boring, but it’s an efficient way for me to work. Of course, you have to come up with your own routine-whatever seems to work for you. Keep trying different ways to approaching your writing until you come up with an approach that’s both efficient and rewarding. Yes, I’m quite tired by the end of the day, but I also feel quite happy with what I’ve gotten done. Let me know your ideas on writing workflow at [email protected].

Facing the Blank Page

Most writers face writer’s block at some point. You have a blank page that’s waiting for you to fill it and you have a vague notion of what you want to say, but the text simply doesn’t come out right. So, you write, and write some more, and write still more, and hours later you still have a blank page. Yes, you’ve written many words during that time—all of them good words—just not the right words.

Every piece of writing I do starts with an outline. Even my articles start with an outline. Creating outlines help you focus your thoughts. More importantly, they help you to see how your thoughts will flow from one idea to the next. Sometimes, if you’re honest with yourself, you’ll discover that you really don’t have anything more than a vague idea that will never become an article, white paper, book, or some other piece of writing. Of course, that’s really the reason for this exercise—to see if you have enough information to even begin writing. If you don’t have enough information, then you need to research your topic more. Research can take all sorts of forms that include everyone from reading other texts on the topic, to doing interviews, to playing. That’s right, even playing is an essential part of the writer’s toolbox, but this is a kind of practical play that has specific goals.

Once you do have an outline and you’re certain that the outline will work, you need to mark it up. My outlines often contain links to resources that I want to emphasize while I write (or at least use as sources of inspiration). A lot of writers take this approach because again, it helps focus your thoughts. However, an outline should also contain other kinds of information. For example, if a particular section is supposed to elicit a particular emotion, then make sure you document it. You should also include information from your proposal (book goals) and your reader profile (who will read a particular section) in the outline. Your marked up outline will help you understand just what it is that you really want to write. In reading your outline, you can start to see holes in the coverage, logic errors, and ideas that simply don’t fit.

Moving your outline entries to the blank page will help you start the writing process. Convert the entries to headings and subheadings. Ensure that the presentation of the headings and subheadings is consistent with the piece as a whole. Unfortunately, you can still end up with writer’s block. Yes, now you have some good words on the page, but no real content. An outline is simply a synopsis of your ideas in a formalized presentation after all.

Write the introduction and the summary to the piece next. The introduction is an advertisement designed to entice the reader into moving forward. However, it also acts as a starting point. The summary doesn’t just summarize the material in the piece—it provides the reader with direction on what to do next. People should view a good summary as a call to action. By creating the introduction and the summary, you create the starting and ending points for your piece—the content starts to become a matter of drawing a line between the two from a writing perspective.

At this point, you have enough material that you could possibly ask for help. Try reading your piece to someone else. Reading material aloud uses a different part of the brain than reading the same material silently. Discussing the material with someone else places a different emphasis on the material. The other party can sometimes provide good suggestions. You may not use the suggestions directly, but listening carefully can often present you with creative ideas that you wouldn’t have considered otherwise.

It’s important not to overwork the piece. Sometimes you need to do something else for a while. Yes, you always want to spend time in research and thinking your piece through, some writing is often done in the subconscious. Fill your head up with as many creative ideas, fascinating thoughts, and facts that you can, and then do something that actually will take your conscious mind off the topic. You might watch a television show or movie, go for a while. have coffee with a friend, take a nap, or do any of a number of other things. The important thing is to forget about the book for a while. Often, you’ll find that the now semi-blank page doesn’t present a problem when you return. Let me hear about your ideas for dealing with the blank page at [email protected].

 

Discerning the Use of the Six Questions in Writing

In a previous post, Creating the Useful Sidebar, I discussed the need for emotion in any book, even technical books. It’s not possible to convey information in a manner that helps a reader understand the technology without including emotion. Facts alone are available in many places on the Internet—what a smart author wants to convey is the emotion behind the facts. Of course, this means adding bias in the form of your perspective on the topic.

Most people know the six questions: who, what, when, where, why, and how. Newspaper authors stress the questions, but anyone who writes technical (non-fiction) materials must consider them as well. They’re good questions. However, most treatise on the topic look at the questions from a factual perspective—what you need to do to answer them and why they’re important. In some respects, it’s better to look at the effect and orientation of the six questions, rather than their factual nature.

The four fact questions are: who, what, when, and where. If you answer these four questions in any piece you write, you have covered the facts. Your writing will likely be as dry and entertaining as the Sahara, but no one will be able to argue that you’ve covered the essentials—the bare minimum. The best authors aren’t happy with just the bare minimum.

The question of how is a slightly emotional question. It not only covers facts, but it also covers some of the emotion behind the facts because you’re presenting a view of the facts. In your (or possibly an expert’s) opinion, this is how the other facts fall into place. For example, a procedure on how to perform a task using a piece of software is your opinion on how to get the job done. Rarely is there a time when your method is the only available method. You discuss how based on your experience. Likewise, looking at the historical context of an event, the how often views the event from the viewpoint of the historian who researched the process, rather than providing a precise and infinitely detailed discussion. A historian could quite well leave out steps in order to streamline the process (to make it easier to understand) or to convey a specific view (in order to support bias).

When looking at the question of why, you enter the territory of pure emotion. It’s impossible to ascertain a factual why, no matter what sort of writing you do. Even addressing the why behind the reason to perform a particular task in a specific matter is based solely on the author’s opinion and is therefore ultimately biased. The why of a situation, any situation, tends to change with time. As an author gains knowledge (facts), experience (knowing how to apply the facts), and wisdom (knowing when to apply the facts) the question of why changes. In addition, memory, perspective, and all sorts of other environmental considerations affect the interplay of emotions that answer the question of why. In fact, you may encounter situations where even the entity that is the focus of why has no idea of why and you must create your own answer to the question.

Great writing revolves around the six questions. The first four are easy, the fifth is a bit harder, but to answer the sixth requires time, focus, and commitment. Let me know your thoughts about the six questions at [email protected].

 

Creating the Useful Sidebar

There are many styles of writing employed for technical writing. Each style has specific benefits and today’s blog post won’t delve into them. However, many of these styles rely on the sidebar to add interest to the writing.

A problem occurs when an author seeks to present only facts as part of any written piece. Readers can find facts on the Internet. What readers can’t easily find is the specific viewpoint that an author presents, which includes supplementary materials in the form of sidebars. A sidebar adds interest to the writing, but more importantly, it provides background material that augments the topic at hand. For example, when discussing smartphone hardware, a sidebar that provides a brief overview of the communication technologies employed by that hardware can prove useful to the reader. The radio frequency transmission isn’t part of the main topic and some would argue that discussing it doesn’t belong at all in a pure hardware discussion, but the addition of that supplementary material is essential to the piece as a whole. It helps present a particular view of the technology that the reader wouldn’t otherwise receive.

Sidebars shouldn’t become a main topic. A good sidebar is at least one long paragraph, but more commonly two or three paragraphs. Never allow a sidebar to consume more than a page of text. For example, a two or three paragraph overview of the history of a technology is useful—a discourse that spans multiple pages is overkill unless the author is trying to make a particular point (in which case, the discussion should appear in the topic proper).

Depending on the sidebar content, you can include bulleted lists and numbered steps. A sidebar should never include graphics unless the book style accommodates such an addition (which is rare). The idea is not to detract from the piece as a whole, but rather augment it in a specific way—to help direct the reader’s attention in a specific manner. Using visual styles and white space correctly help make the sidebar attractive.

Many authors forget the need to evoke an emotional response in any sort of writing, including technical writing. In making a point, the author needs to express the idea fully by making an emotional appeal. A sidebar can perform this task nicely without creating distractions in the overall writing flow. For example, a piece about implementing accessibility features in an application can include a sidebar that contains a case study about the effects of such an implementation on a specific person or within a real world environment. The point is to help the reader understand the implications of a technology and make its use imperative.

Sidebars are an essential tool in the creation of a usable piece of writing that helps a reader understand a topic in ways that many factual Internet pieces can’t. Using sidebars effectively makes your writing better and more appealing. More importantly, a sidebar presents a unique view that the reader identifies with you as an author and sets your style of writing apart from that of other authors. Let me know your thoughts about sidebars at [email protected].