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

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.

Top 4 steps to solicit perfect documentation reviews

To get the best possible reviews from subject matter experts (SMEs), we tech writers can prepare, make our expectations clear and help our reviewers excel at their job.

Soliciting documentation reviews from SMEs can be tricky: They are usually very busy, juggling dozens of tasks, while putting off several more. The last thing they need is a writer to waltz into their office making a demand on their time. Here’s what I do to get an SME to review a manual of 100 pages or 25,000 words. It doesn’t work always, but it’s worth a try – they are the experts after all… 🙂

1. Preparing

Before I even approach the SME, I prepare:

1. Find the ideal reviewer. This might be a colleague who’s installed and/or used the described product. At any rate, it should be someone who is very close to the customer and knows users’ needs and workflows. I also try to find out why the person is the best reviewer, for example, because of recent or in-depth experience with the product.
2. Get permission to ask. I ask the SME’s manager for permission first. This gives the manager a chance to intervene on the SME’s behalf or to suggest someone else – who’s hopefully as good or better. It also helps to deflect the SME’s attempt to defer me to the manager. But it’s not so I can tell the SME: “But your manager said for you to do it.” – I still have to ask and convince the SME!

2. “Save the date”

I ask the SME well ahead of time if she or he will do the review. I usually approach them in person, but it works as well over the phone or via e-mail. If it’s a talk, I follow up with a “save the date” e-mail as a reminder with the essential details. This contact is mainly about the why and the when, so we discuss the following:

• What to review in general and briefly what the manual is for, why or how it’s new, and what’s to review.
• Why the review is essential, namely to ensure we deliver the best possible product and make it easy and effective to use for our customers – and also for colleagues like the SME. This is a good time to show how our joint effort will benefit the customers and that the SME and I have one and the same goal.
• Why the SME is the best person to do the review.
• When to review and what leeway, if any, I have to accommodate the SME’s schedule.

3. “Please review”

At the ‘saved date’, I send the SME my “please review” e-mail with detailed review instructions. This is mainly about the what and the how, so I include:

• The deadline and to let me know asap if there’s a scheduling problem.
• What to review in detail. Usually, I ask the SME to review the complete manual. But sometimes that’s not necessary: Maybe you have several reviews which complement each other. Or maybe you’ve reused topics that don’t require a review.
• How to review. I’ve found that concise general guidelines work best for non-writers. So I tell SMEs to ensure that the manual is complete, correct and usable, and maybe illustrate each of these criteria with a question.
• How to give feedback. Personally, I don’t insist on any specific format, whether reviewers use tracked changes, comments in the margins or handwritten comments on printouts. But if you prefer on a format, let your reviewer know.

4. “Thank you”

After I’ve received and processed all the feedback, or when the manual has been published, I send a brief “thank you” e-mail to the reviewers. In it, I point out how the reviews improved the manual and what major changes I have made. It shows my reviewers that their input matters, it shows my gratitude, and it leaves a good impression for the next time that I need a review.

This works because…

… SMEs are experts who usually enjoy doing their job well. To benefit most from their expertise, give them a chance to do reviews well. So try to supply all the information and instructions they need.

Your turn

What recipes do you have to solicit reviews? How do you get buy-in from SMEs? Please leave a comment!

Are you asking questions right?

Asking questions right (as in: correctly, appropriately) is more difficult and just as important as asking the right questions.

This is not about asking the right questions – with a little trainning and practice, we tech writers usually know how to do it. I find it much harder to ask the right questions right. I take my cue from Bertrand Russell who (allegedly) said:

The greatest challenge to any thinker is stating the problem in a way that will allow a solution.

(Photograph from Wikipedia.)

I think this is a pertinent issue for technical communicators in several ways:

• It’s our job, essentially. Any customer can state countless questions and problems he or she wants to solve with our product. And any developer or engineer can tell us how the product works. It’s our job to connect the two: To restate the customers’ problems – and to answer them – in a way customers find helpful.
• It helps us get useful answers from developers and engineers. Some of the best developers I’ve worked with always kept me on my toes: They would carefully consider my question and then answer it exactly. On the other hand, they would get easily impatient if I came up with a loose question such as “what is this new feature here?”
• It helps us get constructive feedback from reviewers and SMEs. Asking a reviewer whether “this is good documentation” may not get you very good review comments. For a much better way to state the problem, see Craig Haiss’ post about “Turning document reviews around quickly“. For example, he advises to “clearly indicate any questions that you have for the reviewers”. To allow for an easy and efficient solution, he also recommends  “that reviewers can agree to review deadlines beforehand” and to “use a signoff slip”.
• It helps us get support from management. This is probably the most difficult application of the quote. It requires not so much careful phrasing, but also evaluation and judgment of the problem at hand. This doesn’t mean we do the manager’s job. After all, the quote is not about finding a solution, but about allowing a solution. For example, I once had a scheduling conflict and asked my manager whether we could postpone delivery of one of the manuals. Instead, he negotiated to change one deliverable from a manual to a quick start guide, with a manual to be supplied later.

What strategies do you employ to communicate problems to colleagues and managers? Feel free to leave a comment!

Index this!

An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions.

In this post, I share my best advice about building an index. And I ask for your help and opinion on a couple of details.

To make your index entries helpful, anticipate user searches. Think of it as a parallel to online search results. When building an index, think primarily of what users might want to look up and find in your documentation.

To create an index, follow these three steps:

1. Create index entries.
2. Build the index.
3. Clean up your index.

1. Create index entries

1. Scroll through your entire document and search for words and phrases that you want to appear in the index. Select only occurrences with substantial descriptions, not just mere mentions.
2. Create an index entry, depending on your help-authoring tool or other software. Edit the entry to avoid all unnecessary words, such as articles (“a” or “the”) and prepositions (“in” or “by”, etc.).

When creating index entries, consider these issues:

• Redundant entries, where you have several entries for the same thing, may seem wasteful and confusing. However, if users are likely to search for the word “equity” in addition to “stocks”, consider using one of the terms to refer the reader to the other entry.
• Cross-references between index entries is a suitable compromise between usability and completeness: Of course, it is an extra step for the reader to move from the entry “Equity: see Stocks” to the “Stocks” entry. On the other hand, it is much more difficult for writers to keep both entries “Equity” and “Stocks” complete and identical over time. Which do you prefer, as a reader and as a writer: Is it okay for readers to move to a second entry? Or should the page numbers be at each entry?
• Nested entries can help you to structure your index and alert the user to hierarchies of concepts and functions. It also cleans up your index by avoiding redundant words. Don’t have more than two levels, however. What’s your experience: Are nested entries helpful or generally confusing to readers?

2. Build the index

At any time after creating your first index entries, create and preview your index, depending on your help-authoring tool or other software.

3. Clean up the index

After you have created all index entries, rebuild and update your index. Then review the existing index for inconsistencies and go back to the index marks in the text to correct the following issues:

• Omit double entries of the same term, but with different spelling or singular and plural.
• Break up index entries that list more than 5 target pages. Refine index entries, for example by creating additional second-level entries for separate tasks, such as “Setting up”, “Calculating”, etc.

Optimal length and scope of an index is the result of a compromise: Make your index as long as necessary to support readers to use your documentation quickly and efficiently. And make your index as short as possible to spare yourself unnecessary work and the reader confusion.

Whether your index is too long or too short is a matter of judgement. Put yourself into the reader’s shoes once more and review your index. You may find that your index is a little too short and missing some terms that users might also look up.

Read more

Good resources for building an index are these two web pages and three books:

• Kurt Ament, Indexing Single-Source Documents.
• Kurt Ament, Single Sourcing: Building Modular Documentation, “Indexes”, pp. 92-97.
• Thomas Barker, Writing Software Documentation, chapter 14: “Designing Indexes”, pp. 436-453.
• Gretchen Hargis, et al., Developing Quality Technical Information, “Provide a complete and consistent index”, pp. 249-253.
• Jan Wright, The Future of Indexing.

Your turn

Please help me out by weighing in with your experiences and opinions to the questions above. Or feel free to tell me if  I forgot anything? How do you create an index for printed documentation? Should online help also have one, or is the search enough? Please leave a comment.