David Farbey on editing at TCUK12

In his session Letters From The Editor, David Farbey talked about what editors do, what they can do and what they can do better.

What editors do

Basically, it is the job of editors to mediate relationships. They mediate the relationships between the writers, their content, their audience and their organization (such as a company or institution).

More specifically, they still do much of what Robert Van Buren and Mary Fran Buehler laid out in their seminal booklet Levels of Edit of 1980 (a PDF version is available online). Mind you, much has changed since, but many of the basic principles still apply. So David took his cue from the 9 levels of edit to propose 3 classes of edit today:

• The policy edit is for coordination and planning. It ensures that the content is appropriate to the organization and its audience, that it complies with the organization‘s policies and strategies.
• The copy edit handles all the technical issues of content, from spelling and punctuation to formatting and textual integrity. It ensures that the text is functionally correct and clear.
• The developmental edit addresses the content itself in the last and most important stage. It ensures that the language is comprehensible and presents the text’s substance appropriately and clearly, whether it is a concept or a procedure. (This is not the same as a content review! A subject-matter expert reviews whether content is correct and complete, while a developmental editor ensures that such content is presented in clear and comprehensible language.)

 All three classes of edit occur at the same stage in the content workflow:

1. Policy edit: Author and editor plan content production.
2. Author writes content.
3. Subject-matter expert reviews content.
4. Author corrects content according to review.
5. Developmental edit: Editor edits content.
6. Author corrects content according to edit.
7. Copy edit: Editor proofreads content.

Advice for editors

• Check the text and the publication, not the product or the facts that are described in the text, that’s the task of the reviewing subject-matter expert.
• Offer constructive criticism, don’t evaluate or grade the text.
• Mentor the writer, if necessary, don’t manage the writer. If you are his or her manager, put on your editing hat, not your managing hat.
• Create and apply guidelines and policies:
  • Create and comply with a corporate style guide as a searchable collective memory to guide the work of writers and editors alike.
  • Agree on who has the last word.
• When editing topics in structured authoring:
  • Edit in chunks
  • Add a step in the workflow before the copy edit: Editor or writer compiles document
• When editing in an agile environment:
  • Consider when a content item is shippable
  • Consider when the document as a whole is shippable
  • Change the workflow so steps 2. through 4. above become: Write and review in sprint.

Advertisement

Is the new Microsoft Manual of Style for you?

The 4th edition of the Microsoft Manual of Style (MMoS) has been updated substantially in a few crucial areas. It’s indispensable, if you work in a Microsoft domain and worth checking out if not.

Full disclosure: I’ve received a free review copy.

The previous edition of 2004 was becoming quite dated, so a new edition was eagerly awaited by many writers. Here’s what’s new, so you can make up your mind whether you need the new edition. I’ll focus on the first half, the “General Topics” with guidelines, which has the most significant updates.

General impressions

Guidelines have been reshuffled to emphasize the book’s shift from technical publications (such as online help or user manuals) to professional technical communications (which may also appear in web sites, blogs or wikis):

• Previously, the first two chapters were dedicated to “Documenting the User Interface” with screens, dialogs, properties, etc. and to layout. So the message was: “Put proper words pretty on a page.”
• Now it’s the “Microsoft style and voice”, followed by “Content for the Web”. So the new message is: “Know your audience and adapt your sound and your channel!”

Many guidelines and examples have been carried over or edited only slightly from the previous edition, which is fine, because they still apply.

Examples have adopted a new tone: Previously, they were marked as “Correct” or “Incorrect”, now they’re labelled “Microsoft style” or “Not Microsoft style”. Ironically, this modesty is undercut by another change in the text. Previous suggestions to “avoid” certain things have become more strict and now tell you “do not use”.

Layout feels fresher throughout and easier to read. See for yourself at amazon’s Look inside preview.

The 4th edition by chapters

Ch. 1: Microsoft style and voice

A front-loaded new section presents 9 pages of “Principles of Microsoft style” along the lines of consistency, attitude, language, precision, sentence structure and grammatical choices, punctuation, contractions, and colloquialisms and idioms.

This is a welcome framework that can double as a declaration of values or truths to be held self-evident. A tech writing team I know uses the MMoS as the background for their in-house style guide – and with this new section, I guess they can get rid of some of the painfully argued standards and simply refer to this new edition.

I see this section not as a dictate by Microsoft, but as a modest proposal that’s worth considering – and discarding only with good reason. The book’s Look inside at amazon.com allows you to preview most of the chapter, so check it out to see what I’m talking about.

Ch. 2: Content for the web

This important chapter has also been rewritten and moved to the front where it has the prominent position it deserves. But to be honest, it trails several more focused, more expert works.

Still, this is now much more oriented towards useful content and starts with “Make the right content choices” and then goes on to advocate scannable, organized text with lots of links. Additional, but short sections address video, blogs, and wikis as well as task analysis, SEO and social media optimization.

So it’s now a decent attempt with helpful suggestions in the context of a style guide. If you’re at all serious about writing for an audience on the web, you will know or want some of the more expert titles.

Ch. 3: Content for a worldwide audience

This chapter has been edited and expanded, but not substantially changed from the previous chapter 3 “Global Content”. You can preview it, along with the new 2-column layout of guidelines and more information, as a sample chapter at Microsoft Press’ blog post.

Ch. 4: Accessible content

As the audience of technical communications has grown and diversified, accessibility has rightfully gained traction. So it’s a pity to see that this important topic still only gets 4 pages, and not much that’s new to boot.

This is little more than a first check list to make you aware of essential issues and remedies. You can find more in-depth information online.

Ch. 5: The user interface

This is the centerpiece of the manual – and essentially the law in what user interface stuff is called in the Microsoft universe. It’s where the new edition excels and the previous edition was most badly dated.

Much of this chapter had to be redone completely to include ribbons, smart phones, the MS Office 2010 “backstage view” (which is what the File menu section is now called that has replaced the application button). If you’re writing for any Microsoft product, including Windows, you will need this sooner or later.

Ch. 6: Procedures and technical content

This chapter has also been updated:

• Cloud computing is in.
• Guidelines for procedures, reference, XML and HTML  documentation remain.
• Standards on documenting COM and ActiveX are out.

Ch. 7: Practical issues of style

This chapter now combines parts of what used to be chapters on “Content Formatting and Layout” and “Common Style Problems”. It contains essentially unchanged information about cross references, dates, numbers, page layout, titles & headings, etc.

Ch. 8: Grammar

A welcome addition to this chapter are several “international considerations”! If you’re writing for translation or an international audience, you’ll find these tips helpful, such as:

• Avoid passive, because it translates poorly into some languages.
• Avoid imperative in marketing tag lines which comes across as dictatorial in some cultures.
• Avoid “(s)” for optional plural which translates poorly.

Ch. 9ff.

There have been few changes or updates to the remaining chapters on Punctuation, Indexes and keywords, and Acronyms and other abbreviations.

The verdict

The Microsoft Manual of Styles is a very helpful resource. It’s mainly well thought out and solves many problems, so you don’t have to.

If you write for Microsoft environments at all, you need this latest edition to stay consistent.

If you write for the web, accessibility, localization, international audiences, API/SDK documentation, you may need additional resources, either as online or print resources. The MMoS won’t – and in all fairness: can’t – deliver everything you need.

4 benefits of peer editing documentation

Peer editing is the second best thing to hiring a professional editor and brings additional benefits to your tech comm team.

At our company, we technical communicators and some QA analysts all collaborate on Release Notes for our product. It’s a complex financial application, so our Release Notes go to some lengths to explain to customers what exactly is new and how it helps them improve their business and workflows.

Editing and reviewing

This release is the first time I get to work on a language edit for Release Notes topics, together with a colleague who edits, among others, my own topics which I shouldn’t and couldn’t very well edit myself.

Our language edit is one of two editing passes:

• The language edit ensures clear and correct language, including grammar, usage, and style guide compliance, in unambiguous, internationally comprehensible English within each topic.
• The substantive edit, the second pass, focuses on the structural integrity and usefulness of topics as well as the relationship between topics.

Even before the editing passes comes the content review by subject-matter experts who are much better at verifying the actual contents.

I guess the best way to edit is to get a professional editor. Unfortunately, we have neither the time nor the budget to hire one. So I think the second-best way is for technical writers and communicators to peer edit each other’s work. Here are my (overlapping) benefits and reasons why I think peer editing is such a good idea.

The benefits of peer editing

1. Ensure consistency. It’s a great way to improve consistency and common usage among collaborating writers. And it ensures that your style guide works. You really should have a style guide before you peer edit and then use your experiences and findings to fill in the gaps, throw out what you don’t need and change what doesn’t work.

2. Realise growth opportunities. Peer editing is a quick and pretty reliable reality check what each writer does and doesn’t do well, relatively speaking, compared to other writers. And I don’t only mean writing weaknesses. When I first started doing peer edits, I was quite humbled to learn that my criticism wasn’t exactly helping. So I had to figure out how to offer constructive criticism – which I think has made me better and more complete writer. Depending on your team, you may even find that you can teach each other to some degree.

3. Encourage mutual trust. It gives all writers a formal, regular opportunity to check in with each other’s work. It can anchor the good practice to take responsibility for one another’s work – and to learn to listen to others criticize your work. In the best case, it helps colleagues to grow into a team where people trust each other.

4. Enhance group dynamics. If you’ve come to trust each other, you’ll find you collaborate better. Knowing each other’s strengths, you can become more efficient and more productive as  a team, just as members of a sports team knows almost instinctively how the others act.

Your turn

What’s your experience with peer editing? Does it work well? What didn’t work? Feel free to leave a comment.

Use a style guide as a strategic tool

You can use a corporate style guide to enforce the strategic development of your documentation.

That’s my observation as we’re currently moving towards structured, topic-based authoring. The reasons for the move are pretty much the usual ones: To offer more consistent, less redundant documentation that’s easier to use, more efficient to create and maintain and also easier to collaborate on.

To ease in the introduction of topic-based authoring, we drafted a style guide for documentation which now prepares the way for topics. For example, we included specific guidelines for writing headings of manual sections (most of which will turn into topics) among the content guidelines:

• Headings should preferably be unique, if possible.
• Headings should be comprehensible when they appear by themselves in search results.
• Headings of sections that instruct users to do something (which will turn into procedural topics) should start with a verb in the imperative, for example: “Set up a server”.
• Headings of sections that combine several such instruction sections (which will turn into process topics that are parents of procedural toipcs) should start with a gerund verb, for example: “Setting up the installation”.

– The way I describe it makes it sound more deliberate than it actually was. The attitude was more like: Well, we’ll eventually move to topics, anyway, we might as well anticipate the new structure in the styles. We rolled out these guidelines before every writer had received training in topic-based authoring.

Now as we are moving closer to converting existing user manuals to topic collections, we find that many recent manuals which use the style guide not only spell “check box” consistently as two words, not one, but they are also well-prepared to be converted to topics!

How do you use your style guide? Does it only enforce writing and layout conventions, or does it also have a strategic element? Feel free to leave a comment.

Improve documentation with quality metrics

Quality metrics for technical communication are difficult, but necessary and effective.

They are difficult because you need to define quality standards and then measure compliance with them. They are necessary because they reflect the value add to customers (which quantitative metrics usually don’t). And they are effective because they are the only way to improve your documentation in a structured way in the long run.

Define quality standards

First, define what high quality documentation means to you. A good start is the book Developing Quality Technical Information: A Handbook for Writers and Editors from which I take these generic quality characteristics for documentation topics:

• Is the topic task-oriented?
  Does it primarily reflect the user’s work environment and processes, and not primarily the product or its interface?
• Is the topic up-to-date?
  Does it reflect the current version of the product or an older version?
• Is the topic clear and consistent?
  Does it comply with your documentation style guide? If you don’t have one, consider starting from Microsoft’s Manual of Style for Technical Publications.
• Is the topic accurate and sufficient?*
  Does it correctly and sufficiently describe a concept or instruct the customer to execute a task or describe reference information?
• Is the topic well organised and well structured?*
  Does it follow an information model, if you have one, and does it link to relevant related topics?

* Measuring the last two characteristics requires at least basic understanding of topic-based authoring.

The seal of quality

You may have additional quality characteristics or different ones, depending on your industry, your customers’ expectations, etc. As you draft your definition, remember that someone will have to monitor all those characteristics for every single topic or chapter!

So I suggest you keep your quality characteristics specific enough to be measured, but still general enough so they apply to virtually every piece of your documentation. Five is probably the maximum number you can reasonably monitor.

Measure quality

The best time to measure quality is during the review process. So include your quality characteristics with your guidelines for reviewers.

If you’re lucky enough to have several reviewers for your contents, it’s usually sufficient to ask one of them to gauge quality. Choose the one who’s closest to your customers. For example, if you have a customer service rep and a developer review your topics, go with the former who’s more familiar with users’ tasks and needs.

To actually measure the quality of an online help topic or a chapter or section in a manual, ask the reviewer to use a simple 3-point scale for each of your quality characteristics:

• 0 = Quality characteristic or topic is missing.
• 1 = Quality characteristic is sort of there, but can obviously be improved.
• 2 = Quality characteristic is fairly well developed.

Now, such metrics sound awfully loose: Quality “is sort of there” or “fairly well developed”…? I suggest this for sheer pragmatic purposes: Unless you have a small number of very disciplined writers and reviewers, quality metrics are not exact science.

The benefit of metrics is relative, not absolute. They help you to gauge the big picture and improvement over time. The point of such a loose 3-point scale is to keep it efficient and to avoid arguments and getting hung up on pseudo-exactitude.

Act on quality metrics

With your quality scores, you can determine

• A score per help topic or user manual chapter
• An average score per release or user manual
• Progress per release or manual over time

Areas where scores lag behind or don’t improve over time give you a pretty clear idea about where you need to focus: You may simply need to revise a chapter. Or you may need to boost writer skills or add resources.

Remember that measuring quality during review leaves blind spots in areas where you neither write nor review. So consider doing a complete content inventory or quality assessment!

Learn more

There are several helpful resources out there:

• The mother lode of documentation quality and metrics is the book Developing Quality Technical Information by Gretchen Hargis et al. with helpful appendixes, such as
  • Quality checklist
  • Who checks which quality characteristics?
  • Quality characteristics and elements
• Five similar metrics, plus a cute duck, appear in Sarah O’Keefe’s blog post “Calculating document quality (QUACK)“
• Questionable vs. value-adding metrics are discussed in Donald LeVie’s article “Documentation Metrics: What Do You Really Want to Measure” which appeared in STC’s intercom magazine in December 2000.
• A summary and checklist from Hargis’ book is Lori Fisher’s “Nine Quality Characteristics and a Process to Check for Them”**.
• The quality metrics process is covered more thoroughly in “Quality Basics: What You Need to Know to Get Started”** by Jennifer Atkinson, et al.

** The last two articles are part of the STC Proceedings 2001 and used to be easily available via the EServer TC Library until the STC’s recent web site relaunch effectively eliminated access to years’ worth of resources. Watch this page to see if the STC decides to make them available again.

Your turn

What is your experience with quality metrics? Are they worth the extra effort over pure quantitative metrics (such as topics or pages produced per day)? Are they worth doing, even though they ignore actual customer feedback and demands as customer service reps can register? Please leave a comment.

Ragged-right or justified alignment?

Which alignment on the printed page is better: Ragged-right or justified? It seems that ragged-right is preferable, at least in some circumstances.

Today, I’m re-posting a piece that I first published on April 23, 2009, on the now defunct Content Wrangler site and then moved it to this blog as legacy material that was buried in the dark links of history…

I’m revisiting that post for two reasons: To my surprise, this has been one of my most popular posts in terms of search queries, so apparently this is an interesting topic. And I’ve discovered an additional argument with a twist that was new to me…

But first, let’s rewind…

Last year, I wrote:

How do you argue for the preference of ragged-right over justified alignment in print? Searching the web, I soon came across pages which mentioned research, but it was harder to actually find it.

• The National Center on Educational Outcomes put out the NCEO Technical Report 37 which summarizes several arguments and references on the topic in “Table 3. Characteristics of Legible Type”, see the entry on “Justification”. Among them are:
  • Margaret Gregory’s and E. C. Poulton’s article “Even versus Uneven Right-hand Margins and the Rate of Comprehension in Reading”, Ergonomics, Volume 13, Issue 4, July 1970, pages 427-434. From the abstract: “… made no difference for good readers, but for the poorer readers the justified style resulted in a significantly worse performance.”
  • Steven Muncer, et al’s article “Right is Wrong: an examination of the effect of right justification on reading”, British Journal of Educational Technology, Volume 17, Issue 1, January 1986, pages 5-10. From the abstract: “… with reading material presented in right-justified format and in ‘ragged’ uneven line format, subjects performed significantly worse on right-justified material.”
  • David R. Thompson’s paper “Reading Print Media: The Effects of Justification and Column Rule on Memory”, paper presented at the Southwest Symposium, Southwest Education Council for Journalism and Mass Communication (Corpus Christi, TX, October 6-7, 1991). From the abstract: “… best score for recall was recorded in the flush left/jagged right.”
• The UK government agency RNIB’s “Clear print guidelines” on designing printed information that is accessible to people with sight problems: “… avoid justified text as the uneven word spacing can make reading more difficult.”
• The SEC’s “Plain English Handbook: How to create clear SEC disclosure documents” (PDF), see p. 50: “… spacing between words fluctuates from line to line, causing the eye to stop and constantly readjust.”
• … and a thoughtful blog post by Ken Adams with an argument by Ellen Lupton, curator of contemporary design at Cooper-Hewitt National Design Museum, and author of “Thinking with Type: A Critical Guide for Designers, Writers, Editors, & Students”: “… subtle word-spacing and letter-spacing algorithms are needed to make justified text look ‘good’.”

Now I’ve found more arguments:

Karen Schriver’s book Dynamics in Document Design of 1997 is both comprehensive and excellent in explaining the motivation, the tools and the history of good document design. Be warned, however, that it deals almost exclusively with printed document design. Online design is the afterthought that takes up Appendix C, pages 506-517. (That detail right there tells you pretty much what kind of a book it is… 🙂 )

Schriver essentially argues that ragged-right vs. justified is the wrong question – imposed on us by software options, I want to add. According to Schriver, the real issue is word spacing.

Regular word spacing makes for faster reading and more accurate comprehension, in both ragged-right and justified text. Much of the software we use for writing gets word spacing in ragged-right alignment reasonably right without too much trouble. The problem with justified text is that it requires a sophisticated balance of letterspacing, word spacing and word hyphenation which much software apparently doesn’t get right automatically. Instead, it…

…creates a disturbing visual illusion known as “rivers” – paths running vertically through the text that connect the blank spaces between words on adjacent lines. (p. 270)

Here’s an illustration of rivers, from the Wikipedia article on Sentence spacing:

An example of the "river" effect in justified text

So, the bottom line is: If you have rivers in your text, consider ragged-right alignment to do your readers a favor – or invest extra time in spacing your lines nicely.

– If you know of any other arguments or sources that can help us tech writers with alignment and justification, please leave a comment!