Microsoft Word for Medical and Technical Writers

ISBN-13: 978-1604024456
Peter G. Aitken PhD and Maxine M. Okazaki PhD

Reviewed by Robert Delwood, Senior Programmer Writer

The myriad of Microsoft Word books on the market may be a disservice to the readers. Word is a deep application and many of the books try to cover all aspects. This brute force approach doesn’t always work since much of the information isn’t really needed by the readers. In addition, a book “for medical and technical writers” might appear to be the same fare but spun for those markets. However, this book deserves a look. It is not a tutorial and it’s not for beginners, which alone sets it apart. Instead, the authors recognized that it’s neither when Word is working properly that users need help nor even afterwards. It’s preventing the trouble in the first place. The emphasis here is prevention, and the authors offer their experience into the more obscure parts of the application.

The book format is different. They do two clever things. The first is that the book is spiral bound, allowing it to be laid flat while reading. The second is that the 8 ½” x 11” pages have larger print. The book can be on the desk and it’s still easy to follow the procedures, typically about five steps with explanation. The title is misleading. Ostensibly for medical and technical writers, there is not much specific to those fields. Rather, the authors tap their experiences of using Word to create long, complex documents with exacting requirements. It’s in those cases that many of the problems come up. Trouble areas include tables, cross references, automatic numbering, templates, and table of contents (really to name only a few). It’s also surprisingly short - 158 pages. Don’t let all that deter you. The tips, insights, and suggestions could save you a lot of time and grief.

The book covers Word 2003 specifically. Office 2007 is too new to tell if the problems are the same, or if the Word 2003 solutions still apply. There are nine chapters covering the common source of problems, from general options, to styles, fields, tables, templates, and best practices. Each chapter discusses the important options or cases, includes a brief discussion about the value or contribution of that item, and often includes a recommendation for using or not using it. For example, the first chapter discusses general options. Their tip is to use AutoText for complex words, a feature many users forget about. For medical writers, a monograph about Neisseria gonorrhoeae may require that name to be used dozens of times. In this case, add it as an AutoText entry and Word will prompt the writer to complete the term after only four letters. Their reason for using AutoText rather than AutoCorrect is that writers will have explicit control over the replacements. AutoCorrect makes automatic replacements, which may be acceptable for commonly misspelled words, but you may want to generally avoid letting Word do things automatically.

In another example, styles are often the cause of problems. Chapter two reviews the seriousness of styles and how to use them properly. We are reminded that all formatting should be a part of styles. That is, directly applying bold to text means that text can not be controlled effectively through styles and templates, and that copy and pasting that text introduces that error into other documents. The document’s owner can ask at any time not to have those words bolded. In addition, if the document belongs to a client, not having it styled correctly can look unprofessional for you and cause rework for them later; hardly a way to endear yourself. Furthermore, they recommend not creating new styles based on the Normal style. It is better to make a new one based on No Style. The reasoning is that Normal style is a common style and if the document is attached to another template (such as Normal.dot), it is possible for the Normal style to be defined differently. This may display unintended results. In combination with those, they recommend to always keep the New Style dialog’s options Add To Template and Automatically Update options unchecked. Each of those options can change the template, and template changes should always be explicit, not automatic.

Finally, it’s not possible to list all the causes for all of Word’s problems. It’s just too large, too complex, too buggy, and with too many subjective design features to list. Some features are known to cause problems and are best avoided, such as master documents, auto numbering, tables, and revisions. In the same way, the following are known to also cause problems: Editing the document on different computers, different Windows versions, and different Word editions; using Compare and Merge on long documents, and repeated use of Track changes, especially if done by several different users. Obviously it’s not possible, or even practical, to avoid all of these. In those cases, just be aware that problems are likely to be introduced. In all cases, “always always save your document.” This includes having multiple copies. The reasoning is that it’s easier to recover from a recent version than an older one. When you do a backup, don’t rely on Word’s automatic save feature but use Save As to create a new file without overwriting the existing file. They also recommend saving as often as every 30 minutes.

It’s clear, the more you know about Word’s inner workings, the more you distrust it.

 Mastering Regular Expressions

Third Edition
ISBN 10: 0-596-52812-4/ISBN 13: 9780596528126 [Pages: 542]
by Jeffrey E. F. Friedl

Reviewed by Robert Delwood

The mundane text search has been long overlooked. DOS users remember the DIR command to find files (such as DIR *.txt), Windows users have the Start >Search feature, and Microsoft Word, the Find dialog. These are all convenient operators but generally are limiting in that you have to know exactly what to look for. A generalized pattern search is not always possible. The scope of the problem becomes larger with increasingly huge disks and file proliferation. How do you find information across many file locations and formats, especially when you don’t know the specific text? That’s where regular expressions (also called regex) come in. These are extremely flexible search or replace methods capable of finding text patterns in a file or files.

As a simple example, you’d like to make sure that a team member’s name, Jeffrey, is spelled correctly each time. Forms you might want to look for would include Jeff, Jeffrey, Jeffery, Geoffery, and Geoffrey. In Word, you could do a find, or likely five finds, for a single file and still end up with mismatches such as jeffreyi or Jeffers. First, you want to search all the files on the Web server. Later, you want to change all those occurrences to Jeffrey. Finally, you want to make sure that Jeffrey always appears as his full name Jeffrey Smith. The simplest requests are impractical with 32,000 files, and the last three requests are not possible. A regex can do this. For a more complex example, you need to check all your files for matching  and <\p> statements. These are real world example of problems that need to be solved. The last example can be solved with a regex such as: % perl -0ne ‘print $ARGV\n if s/\<p\>//ig != s/\<\\p\>//ig *

This statement likely doesn’t make sense right now, but it does show the power of a single line. The examples are limitless. You can search for date patterns, turn URLs into links (a common enough task to get its own name: urlify), change HTML tags, or extract an IP address. Regex is an invaluable skill, and you may wonder how you ever got along without it. TiVo users already know this feeling.

A series of books attempt to demystify these tools. Mastering Regular Expressions (third edition) by Jeffrey E. F. Friedl tries to make sense of these. Part tutorial and part cookbook, it’s mostly a story introducing a regex state of mind. You can get new perspectives for creating solutions with a deeper understanding. This is consistent with the author’s “teach a man to fish” approach. Regular Expression: Pocket Reference by Tony Stubblebine is a small reference book (which does fit into a shirt pocket) that concisely lists the syntax and features 11 common implementations including Perl, .NET, Java, the vi editor, and shell tools.

There are several things to understand first.

• Regex is not a singular entity. It is a generalized concept with individual implementations such as Unix, POSIX, .NET, Java, Perl, Visual Basic, and VBScript, among others. Each has its own version and differs slightly.
• You will need an application to use regex. Windows has many downloadable versions (many of them free). eGrep is a common tool available at http://www.gnu.org/directory/grep.html. Windows has two older command line versions still available: FIND and FINDSTR.
• Regexes are programming languages ranging from simple to complex. Programmer-writers and programmers can make the most of these tools, but all users can write their own expressions. If nothing else, eGrep is a better replacement for the Windows Search.

Expressions

You can start with simple forms of finding exact text such as “cat,” which finds all words with the letters c-a-t in that order. This includes cat, catalogue, and vacation. Regexes are not word based. It’s better to think in terms of patterns than words.

Matching exact text is only the starting point. You can find one of among a group of characters by using brackets ([]).  <H[123]> finds HTML headings 1 (<H1>), 2 (<H2>), and 3 (<H3>), but no others. A dash indicates a range <H[1-3]> and has the same results. You can find groups of letters by using parentheses. The Jeffrey problem from above can be solved a number of ways including (Geo|Je)ff(re|er)y. A caret excludes characters. <H[^4-9]> finds all headings except 4 through 9.

Taking pattern matching one step further, the dot character (.) finds any sequence of characters (this is similar to the * symbol in DOS). Editors sloshing through Word-generated HTML may appreciate those matches within a span statement.

Repetition quantifiers match multiple occurrences. The asterisk (*) matches zero or more of the immediately proceeding characters (it would be all right not to find any matches). For instance, the <HR> tag can take several forms, including having superfluous spaces, such as <HR●> (● represents a space character). A basic search of <HR> would not find those instances. A better search, <HR●*>, matches any number of trailing spaces. <HR> tag can also take the form <HR SIZE=14> (along with any number of extra spaces). The best search, <HR(●+SIZE●*=●*[0-9]+)?●*>, catches any HR statement regard of the SIZE value or spacing inside the tag. The more you know about the target pattern, the better searches you can construct. Of course, there is a book’s worth of additional options.

Book Structure

The book’s 515  are divided into three distinct parts:

• The first three chapters address the semantics and creation of individual statements and will have the most interest to readers new to regex. Reading these chapters should give new users a solid foundation and give them the ability to write their own searches.
• The next three chapters contain details about how the expressions work. This information about the search engines aims at optimizing the statements for speed and accuracy. Experienced users may find these three chapters the most applicable because they explain engine types, matching hierarchies, anchors, and order of precedence.
• The last four chapters are specific to an implementation such as .NET, PHP, Java, and Perl.

It’s hard to write a book for a wide range of users. In many cases, it doesn’t satisfy any set of readers. However, Mastering Regular Expressions does succeed in communicating different goals to different users. In short, new users get a proper introduction to the power and versatility of regex. Experienced users will be able to optimize their searches.

GUI Bloopers 2.0: Common User Interface Design DON’Ts and DO’s

ISBN 1558605827
Jeff Johnson.  2007.  Morgan Kaufmann Publishers.  [ISBN-13: 9780123706430. 576 pages.]
Reviewed by David Dick

Once upon a time, graphical user interfaces (GUI) were found only in operating systems for PCs. Today, we are confronted with a GUI when we use self-service checkout counters, when we pay bills online, and when we use our mobile phones, to name a few examples. Whether we can complete our transactions or accomplish our tasks depends on having a GUI that is easy to use and easy to understand. No doubt you have seen people confused with the touch-screen menu at the self-service checkout counter, or abandon their online shopping cart because the form is confusing. You may well have chosen a competitor’s brand of income tax preparation software because it is easier to use. Frustrated users mean lost income and products that fail in the market place. When GUIs fail, that’s when companies call a user interface designer like Jeff Johnson to change poor design into great design.

The first edition of GUI Bloopers heralded Johnson’s first work as a book author. GUI Bloopers was intended for software developers who often work double as user interface designers, development managers, and new user interface designers. But GUI Bloopers also gained popularity among teachers and technical writers who wanted to understand the rules of good user interface design. Readers’ feedback, new software products and Web applications on the market inspired Johnson to write an updated version—GUI Bloopers 2.0.

GUI Bloopers 2.0 describes common user interface mistakes found in today’s software products and services, and provides design rules and guidelines to avoid them. Johnson describes the design decisions that lead to misuse of controls, poor navigation, prose-riddled labels, bad design and layout, faulty interaction, and poor responsiveness. GUI Bloopers 2.0 is well illustrated with hundreds of examples from real products and online services, and stories from his own experience. To compare and contrast good and bad design, Johnson gives a “thumbs up” for good design and a “thumbs down” for a blooper.

The book contains the following chapters:

Chapter 1, First Principles, describes nine principles of product design: focus on the users and their tasks, not on the technology; consider function first and presentation later; conform to the users’ view of the task; design for the common case; don’t complicate the users’ task; facilitate learning; deliver information and not just data; design for responsiveness; and try it out on users and then fix it. Too often, the rush to deliver products means ignoring one or more of these principles. Johnson could have omitted this chapter and jumped right into describing GUI bloopers, but it provides an informational foundation for the discussion of bloopers.

Chapter 2, GUI Control Bloopers, is the first of six chapters dedicated to GUI design details. It describes the most common misuses of controls (i.e. check boxes, tabs, input fields and buttons) and how to avoid them.

Chapter 3, Navigation Bloopers, emphasizes the importance of cues to let people know where they are, where they have been, and where they can go. This chapter describes the most common navigation mistakes and how to design effective navigation cues.

Chapter 4, Textual Bloopers, describes how inconsistent and unclear terminology, poor writing, jargon, and misleading text can confuse users. The typical GUI contains a lot of text, and if it’s poorly written, users can easily get lost. Peer reviews of the user interface by developers do not uncover these errors if they cannot recognize them as confusing. For example, an error message that describes a script error is informative to a developer but meaningless to a user. Johnson offers suggestions for educating development teams about good writing and acceptable terminology, and how to conduct reviews to identify textual bloopers.

Once the GUI controls have been added, properly labeled and any supplemental text has been written, it is time to decide on presentation: layout, colors, and text fonts.

Chapter 5, Graphic Design and Layout Bloopers, presents guidelines on layout and window placement, colors, and text fonts. You will learn valuable presentation guidelines that will make user interface easier to read and understand. Unfortunately, Johnson was unable to provide examples of bloopers showing poor use of color because the book is printed in black and white. However, he covers color bloopers in a Web Appendix at www.gui-bloopers.com.

Chapter 6, Interaction Bloopers, is the first of two chapters that describe the mechanics that underlie the user interface. In this chapter, Johnson presents the user interface design principles that affect human perception, reading, information processing, and problem solving. The chapter clarifies why violating these principles results in a software product that is hard to learn and frustrating to use. Some of the design mistakes covered in this chapter are driven by business rules and processes mandated by clients and corporate policy. If those business rules and processes do not contribute to usability, this chapter will educate you on how to make an argument for improving interaction.

Chapter 7, Responsiveness Bloopers, is the second chapter that deals with the mechanics that underlie the user interface design. In this chapter, Johnson describes the reasons for poor responsiveness and the design principles for improving responsiveness. Before I read this chapter, I assumed that sticky buttons, frozen cursors, and lagging scrollbars (to name a few) meant that my PC was too slow. After reading this chapter, I learned not to confuse responsiveness with performance.

Chapter 8, Management Bloopers, describes management misconceptions and mistakes that lead to poor product usability. Other authors have dedicated whole books to management-level problems that affect usability. Johnson could have easily omitted this chapter and listed those books as references. However, he does not just rant about why poor management leads to poor usability; he provides strategies and suggestions to educate management about usability.

GUI Bloopers 2.0 is supplemented by a Web site, www.gui-bloopers.com, which provides the following information:

GUI Bloopers checklist: a check list of all of the types of bloopers in the book to facilitate checking software before release.
Web Appendix: Color Bloopers: two bloopers about poor use of color that could not be included in the book because the book is not printed in color.
More bloopers: additional bloopers not included in the book, starting with bloopers that did not make the “final cut.”

GUI Bloopers 2.0 earns my “two thumbs up.” It is well written, well researched, and an essential resource for anyone developing software products and Web applications.

Manage It! Your Guide to Modern, Pragmatic Project Management

Johanna Rothman. 2007.  Pragmatic Bookshelf. [ISBN: 978-0-9787392-4-9. 365 pages. $34.95 USD.]

Review by Robert Delwood, Senior Programmer-Writer

Every company has their own life cycle model. This is the set of procedures guiding them toward a product release. In practice, it’s not long before they have to vary from the model. General Eisenhower understood this when he said, “Plans are useless, planning is indispensable.” In addition to the inevitable problems that come up, the model won’t even be appropriate for all groups. Considering the diversity of a release (for software, this includes developers, testers, program managers, writers, and evangelists), no single model meets everyone’s needs. What do you do in those cases?

Manage It! by Johanna Rothman, takes a detailed approach toward “pragmatic project management.” Written mostly for the project manager, the ideas apply equally to other groups, if only in a smaller way. Given the few project management books specifically for documentation teams, these approaches adapt easily. Its 365 pages define issues such as starting a project, life cycles, estimating and scheduling along with their pitfalls, statusing and keeping a project on the right path, through to managing the release.

“Pragmatic” is a good term. The book introduces the idea that modern project management has to be a flexible system, using creative approaches and selections from among established models. It discusses a dozen broad topics in a format of problem description, solution, and something that is not always mentioned in books; how you can implement the solutions. The following are three issues discussed in detail: project management, managing managers, and scheduling.

Project Management

There is no “One True Way” for all projects. For example, an initial product release, a point release, and a bug fix version are all very different projects, just as is an initial documentation release, a maintenance update, and a Web-based How To suite. Slavishly following an inadequate model introduces more risks than it solves. Understand that project management is really risk management. Here, a risk is any condition that threatens to interfere with the plan. That means knowing the strengths and weaknesses of different systems and taking the useful features to meet your goals. For example, the project as a whole may be using the serial model, but your documents need an incremental approach for the added feedback and technical inputs. There are four basic types.

• Serial. Also called waterfall, this is the classic model. Milestones are clearly scheduled and follow a sequential approach, and expectations are easily managed, but useful scheduling is next to impossible since the serial nature of the process hides delays and risks, and limits feedback. A common variation is called rolling wave scheduling, and it allows for additional planning at each milestone.
• Iterative. This breaks down processes into smaller serial processes. The product prototypes evolve each cycle. This handles technical risk better, and the smaller timeboxes allow for better feedback. But the finishing schedule can be difficult if the prototype takes too much time and costs can be larger since the riskiest parts are worked on first.
• Incremental. This works best when you don’t have constant contact with the customer or component or cross-functional teams work independently to complete their tasks. The results are then rolled up in the next milestone. Schedules are more accurate as feedback is from multiple team members. Workers can be added or small teams can be used (useful when resources are  scarce). Requirement changes can be accommodated, but keep in mind that changes in the architectural foundation affect the entire product.
• Iterative/Incremental (now known as agile). This breaks down each cycle to even smaller parts, as short as a week. Scheduling is the most flexible since you never plan in excess of what you need for the cycle. Team members may be reassigned after each short period. Requirements change less during a short period. Cost can be managed since priorities can be re-ranked. Project leaders must make strong decisions up front since significant re-ranking of priorities can cause extra work. The work environment must support flexibility.

Managing Managers

Project management boils down to management. The classic view is of a person directing the time and efforts of subordinates. You also manage your own time. While some amount of pushback (such as on a schedule or proposed feature list) is normal, recognizing risks introduced by your management is important. Sixteen types of risks are identified. Among them are:

• Bring Me a Rock. The boss insists on results but is vague about what is needed. The team, therefore, always brings the wrong rock. The pragmatic manager (you) has options for asking for explicit details, explaining why you brought that rock, trying to get an explanation, and then solving the underlying problem.
• Queen of Denial. The boss doesn’t face up to reality and has the attitude of “if you work hard, you’ll meet the goals.” The key is that you are not in denial. Be clear about the costs and results, or try to have managers explain the problems and suggest solutions.
• Split Focus. These managers schedule more than 100% of your time or set tasks that are too divergent. They say yes to all projects, thinking doing more than one task is always good. Try approaching the team to point out time/resource limitations, setting up shorter iterations, or using ranking requirements.

Planning and Scheduling

The pragmatic manager plans enough only to get the project started. It doesn’t have to be perfect. Know that things change quickly. Planning should be empirical (shorter-term goals and using feedback to gauge process), rather than the commonly used predictive approach. Scheduling is the hardest part of the process since it’s the most subjective, least defined, and within hours, will be out of date anyway. Expect to iterate schedules after milestones. The following can be used in any combination:

• Top Down. Use firm dates as the milestones and fill downwards.
• Bottom Up. Use individual component goals and fill upwards.
• Hudson Bay. Use this if the tasks are completely new to the team. The term refers to fur outfitters of the Hudson Bay Company. The trapper was required to set up camp several miles away from the store for a few days. This ensured they didn’t forget anything later. Start with small tasks and work up to more complicated ones.

Globalization and Its Enemies

by Jeff Staples, STC Director at Large

Daniel Cohen. 2006. Translated by Jessica B. Baker. Cambridge, MA: MIT Press. [ISBN 978-0-262-03350-3. 192 pages. $27.95 USD.]

Globalization has generally been presented as a product of a modern world with “no borders” and a “think global” mentality. In daily life, at least in the USA, we hear about globalization, outsourcing, and work being sent abroad. Daniel Cohen relates that globalization has existed since the Spanish conquistadors and has seen various “rebirths.”

In approaching Cohen’s text, I was enthralled with Cohen’s insight that “one civilization destroys the other, not because it is more ‘advanced,’ but because it is immune to its own diseases, protected against the perverse effects of its system” (4). He goes on to provide an example of his theory by recounting how the French built a road to free a small mountain village from its isolation and provided DDT to combat malaria and typhoid fever in the area. However, these “helpful” measures destroyed the traditional society by reducing deaths, thus increasing the population, who then required more food and thus needed more livestock, which then destroyed the soil, and so on.

For Cohen, the primary problem with globalization today is that “globalization does not keep its promises” (166). Basically, today’s advancements in communication technologies makes globalization a vehicle that exposes such benefits as wealth and high standards of living to all people, including those who do not share these benefits. However, the economic forces are not present that assist these individuals in poor countries to make the images that they see become a reality. Thus, globalization just makes these people more aware of what they don’t have, without supplying the resources to obtain something better.

Cohen delivers a book that should have substantial appeal to individuals interested in economic influences on historical events. Throughout the text, he weaves his thoughts on globalization (and what he perceives as “enemies”) by focusing on economic and financial strategies that influence a country’s historical development and its global standing.

Cohen, an academic, at times digresses to a myriad of “academic speak”, but overall has delivered a clearly written text. However, the text is not written in a straightforward or clear manner to specifically identify “globalization and its enemies.” Instead, he provides a wealth of information, which he provides as proof of his assertions about the disastrous history of globalization, but which requires the reader “to read between the lines” to make a literal connection.

Had Cohen delivered his text in a more straightforward analysis focused toward industry, perhaps the reader could have then used the information in his or her known working environment. Alas, the reader must work with what Cohen has chosen as his delivery of choice.

For the technical communicator, Cohen’s book offers the perspective that globalization is nothing new and he provides examples of its impact on society through various periods. Although it’s a challenge to foster a literal link with the information he presents, the communicator can reason that today’s globalization is just a new chapter and one that will eventually lead into another chapter in the history of globalization and with it, a new perspective.

The text includes a “Notes and sources” section and an index, which is fairly extensive for a short book.