Top 3 fixes when editing topics

A few recurring issues distinguish the editing of structured topics from that of other content. Here are the top 3 issues I’ve recently found while editing topics for language, consistency and structure.

1. Topic heading is weak

A heading can seem appropriate when you’re writing the topic, but it may still seem weak when you see it in the context of the entire help system, for example, in a list of search results.

Write topic headings so they give your readers a precise idea what that topic is about. Yes, that can be challenge when you’re trying to be precise and concise at the same time:

• Indicate what kind of information a topic contains. For task topics, consider starting the heading with an imperative verb. For concept topics, consider using noun phrases.
• Offer enough context so your reader can identify what area or functionality in the product the topic refers to.

2. Purpose or user benefit is missing

A topic can look great and complete: It does whatever self-contained thing it set out to explain. But if it doesn’t also contain a why and wherefore, it’s harder for the reader to understand whether they’ve come to the right topic and how it helps them.

Include the purpose or user benefit of whatever the topic describes early on, in the first or second paragraph. Answer the readers’ potential questions:

• Why is it important to know about or do whatever the topic describes?
• How does this connect to my work?
• How does it make my job or my life easier?

Be careful to describe the purpose or benefit of the topic’s content, for example, the actual concept or task, not the purpose of the topic. Focus on: “This function helps you…”, not “This topic tells you…”

3. Topic mixes topic types

A topic can look complete, comprehensive, and self-contained, but if it goes overboard and describes both, functional tasks and underlying concepts at length, it tends to overtax the patience of those who only need to know one of the two. It also makes it harder to assign a clear heading, to structure the topic clearly and to reuse the topic in additional contexts you might not yet know about.

Stick (mainly) to one topic type per topic. If you’re using the traditional triad of concept, task and reference topics, divide them accordingly, but keep it pragmatic. Ray Gallon and Mark Baker have both shown how a little conceptual information in task topics can go a long way, but they shouldn’t replace entire concept topics. Also see my previous post When topics don’t quite work from two years ago.

Summary

These top 3 issues and several others basically have the same underlying reason: We tend to write topics in the context of a function or a window, but that context is not necessarily familiar or identifiable to our readers.

Issues with the same reason also share the same basic solution: We should focus on writing topics in the context of our readers, their environment and their tasks in it.

Advertisement

Advanced visual editing with Leah Guren at tekom12

Leah Guren presented a fast-paced, entertaining session full of relevant tips to improve visual editing in documentation. While some of her advice refers to page-based deliverables, most of it also applies to online output styled by CSS.

First, Leah showed how good layout improves usability, while poor design actually hurts the success of your documentation:

• Good design means to apply layout that supports the document’s meaning. So use numbered lists for sequenced information, bullet lists for unordered information and tables to (visibly) structure information.
• Poor design means information is hard to find, hard to identify and simply looks unprofessional.

To apply good layout design, you can use 5 principles which make up the acronym PARCH:

1. Proximity.Ensure that items and information that belongs together appears together:
   • Place headings closer to the text they belong to below than to the text above.
   • Arrange list items in chunks, so each item is easily recognizable as a unit of its own.
   • Offset individual paragraphs to clarify paragraph integrity.
2. Alignment. Ensure that vertical alignment uses few, sensible points of reference, so bullets and numbers are indented to one vertical line, the list items introduced by bullets and numbers to a second vertical line. Also ensure that text flow in tables is clear and it’s easy to identify which table items belong to the same row.
3. Repetition. Repeat visual patterns to signal intent and to ensure consistency. This applies to how you use colors and icons and where you place items within a topic or on a page.
4. Contrast. Apply contrast to focus the reader’s attention. For example, use larger and/or bold fonts for headings.
5. Hierarchies. Use hierarchies of topics and sections to nest information. This also means to avoid single children of parent topics, because you logically cannot divide a chapter or section into just one sub-section. (As a solution, you can either move the child topic to the parent level, or if more child topics are on the way, have a placeholding topic that introduces or previews the forthcoming topics.)

Then Leah offered some additional tips:

• Use icons to allow for quick filtering. Like a Thai restaurant that marks hot dishes with icons of one or several chili peppers. Or vegetarian dishes with a leafy icon.
• Choose your fonts smartly and consistently.
• Don’t design for exceptions. For example, don’t create a standard table with wide cells, just because you may have one or two cases which otherwise need to wrap around.
• In headings and paragraphs, apply white space only above for consistency.

And as final recommendations:

• Learn about design – it’s pretty easy already with stuff you can find on the web or paperback books.
• Ensure you get and stay involved in the design of your documents.
• Experiment and try new things – be brave, but stay sensible.

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.

Top 3 reasons to do a language edit

There are several good reasons to do a language edit and most have to do with the overall quality and usability of your documentation. That’s the lesson I learned while editing our upcoming Release Notes for language.

The language edit is the unloved stepchild of the tech writing process: It is frequently last in line and gets less attention than the actual writing and the content review. Yet it really impacts the quality of the documentation, precisely because it occurs so close to publication. Here are three benefits of a language edit.

Correct, clear and consistent language

The most obvious benefit is to ensure that the language in the document is correct, clear and consistent. This is why you do it in the first place. And it is especially important if the documentation is written by several authors. Even if you have a really good and detailed style guide, you’re bound to get different ways to interpret it – to put it benevolently… 🙂

Ensuring clear language requires a language editor who is well-versed in the subject – but not so steeped in it as subject-matter experts (SMEs) who may review content who often have too much of an insider’s view and won’t spot potential misunderstandings. (Many SMEs are also uncomfortable with reviewing language, either because they lack the skills or because it distracts them from the review they should be doing.)

Ensuring consistent language requires an editor who reads across the complete document – instead of distributed authors and reviewers who work on a chapter each. Most chapters I encountered had their distinct style, but the differences between chapters couldn’t have been greater if they had been in entirely different documents. This seems to be a stylistic issue at first, but it spills over into the other two reasons for a language edit, so follow me on to the next item which is…

Consistent structure

Our standard operating procedure for writing Release Notes contains a standard structure which each entry should follow. Essentially, it looks like this:

• Summary of enhanced or new feature
• User benefit of feature
• Prerequisites of feature
• How to use feature
• Results and next steps of feature

Depending on the scope of an enhancement, some of these structural elements per entry are optional. A new menu option may be self-explanatory enough, so we don’t need to point out the user benefit, and there are no special prerequisites. The whole entry may be but two sentences long.

However, it is a matter of judgment how many details and customer guidance we want to provide. For a team of distributed authors, this is almost impossible to agree upon before hand. A language editor can help to ensure consistent structure. This may require consulting with the author about missing structural elements, but if they’re quick to respond, it is well worth the effort.

Raising documentation standards and value

While you are talking with authors about missing elements, this is a good chance to offer feedback about recurring issues. I’ve noticed that some authors have their “favorite” mistakes. One has missed a guideline in the style guide and keeps repeating the same small mistake. Another may have a larger misunderstanding, whether it’s about topic types, the use of personas, etc.

The language editor not merely improves a document, but in the process also performs a thorough audit of current documentation practices. So she or he can help to ensure adherence to documentation standards and raise the value of the documentation you publish. A language edit is often the last chance to ensure your final document feels and works as it should and lives up to your corporate and documentation standards. Omit it at your own peril.

For more about editing, see my earlier post “Editing for tech writers“.

– Do you do language edits? What benefits do you get from them? Which shortcomings made you wish you had done one? Please leave a comment.

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.

Recommended read: Practice technical writing

Becoming a better tech writer requires practice.

Mike Pope, tech editor at Microsoft in Seattle, has a brilliant blog post about 12 ways to practice tech writing. The catch is he means “practice” like a musician, so you learn to do stuff better than yesterday – instead of just doing the same things over and over.

Over the last years, I’ve tried all 12 ways, and they’ve all helped me to become a better writer. And most of them can be fun, too, at least most of the time… 🙂

Here are just six of the ways as a teaser, but I highly recommend you head on over to Mike’s post to find out about all of them with details and examples.

1. Read other technical writing attentively.
2. Read about writing.
5. Writing something outside your usual material.
7. Edit someone else’s work.
10. Learn new tools and new ways to use your existing tools.
11. Talk to other writers.

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.

Editing for tech writers

Tech writers don’t just write, we frequently also edit what our peers have written. As Tom Johnson recently tweeted:

Can’t decide if the technical editor role is dead or if technical writers have evolved into this role as their new default.  8:40 AM Apr 23rd

I wouldn’t call it a “default role” for us writers, though the “pervasive idea in companies that ‘anyone can write'” creates more demand for this role (paraphrased from another tweet by Tom three hours later).

I’ll gladly edit the work of another tech writer (and rely on their feedback in return), but I’m less likely to “clean this up by noon”: I’m not grammar boy, and if anyone can write, then anyone can also clean up behind himself… If and how I edit depends on the situation. But what do I mean by editing?

(And what do I mean by that photo? Nothing in particular. Except maybe: How do you illustrate editing? :-))

Editing 101

When it comes to technical editing I have three heroes: Robert Van Buren, Mary Fran Buehler, and Jean Weber. Robert and Mary put together the ultimate tech editing guide back in 1980, called Levels of Edit. An STC edition from 1992 is apparently out of print, but there’s still a summary and a PDF version out there. Their booklet is the most comprehensive and best structured guide to tech editing that I know. They distinguish nine (!) types of edit:

1. Coordination
2. Policy
3. Integrity
4. Screening
5. Copy Clarification
6. Format
7. Mechanical Style
8. Language
9. Substantive

Depending on how thorough your task and how much time you have, you go through all or only some of the levels. In fact, they suggest five different levels of edit for different purposes of a document. Unless you create a production edit for a printing house or publisher, you will probably omit types 1 and 5. The others may be more or less relevant, depending on general policies and what kind of document you’re editing.

I find the nine types of edit so clear and well-structured, because they help me to stay consistent and focused in my editing:

• When I do an integrity edit to make sure that the table of contents and index are up to date and show the correct page numbers and that all lists are numbered correctly, then I don’t want to worry about misapplied templates, line breaks, text justification and alignment.
• When I do the mechanical style edit to assure compliance with the corporate style guide, I don’t want to haggle with Oxford commas and dangling participles.

Yes, it does mean that I go through the same document repeatedly, but I find that the additional time spent scrolling or turning pages is made up by the better focus.

Editing the work of others

You can edit your own work, but I don’t recommend it: I find I’m too entangled in my writing, constantly tempted to fix an odd phrase here, a less than perfect table there. If at all feasible, have your work edited by someone else, and edit the work of colleagues.

This is where my third hero Jean Weber comes in (no relation to me): Jean knows all about how to work with editors – or, if you’re an editor, how to work with people who write. She also pointed me towards Levels of Edit.

Jean is in Australia and, according to her website, retired from paid work. But she’s so generous, she shares her knowledge and experience. I found three articles especially helpful:

• Working with a technical editor – where she explains what tech editors (or people filling that role) do and feasible scenarios to use them
• The role of the editor in the technical writing team – where she describes what people expect from editors, what they really do and how they interact with other documentation roles
• Beyond copy-editing: the editor-writer relationship – where she shows how the editing role can be filled successfully

Your turn

How do you edit? How are your documents edited? Do you edit your own work or someone else’s? Feel free to share issues and insights in the comments.