@techwriterkai’s popular posts, part 1

My blog is taking a spring break for two weeks and is due back on May 9.

I thank you for reading and commenting. Your support and feedback is the lifeline of this blog and make it all worthwhile!

As I’m taking a break, I invite you to check out (or revisit) a few of my all-time popular posts:

2011 megatrend in technical communications

… in which I roll three predictions by Sarah O’Keefe for technical communicators into one megatrend: To position tech comm as a business in its own right – or to be redundant in the long run.

Top 10 things that users want to do in a help system

… in which I draw parallels to a department store or a library to illustrate how customers want to navigate each one.

Top 4 benefits of writing a tech comm blog

… in which I get a little more specific about what exactly I get out of this blog.

Bonus recommendation

If you’re looking for a soundtrack for spring that sounds all mediterranean, outdoors-y, party-esque, incredibly joyful and danceable, I highly recommend “Mlah” the criminally overlooked debut album by Negresses Vertes. Start with tracks 4, 7 and 10.

Your turn

Which older blog posts do you find worth revisiting (whether it’s from my blog or any other tech comm-related blog out there)? What’s your spring soundtrack? Feel free to leave a comment!

Advertisement

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.

STC Summit Timetable

The STC Summit is a month away, so what better tool to build up a pre-conference buzz than a timetable that shows the plethora of panels and presentations side by side? I couldn’t find one on the conference web site, so I made a PDF timetable with links that’s current as of yesterday, April 13:

Caveat emptor:

1. The Tuesday slot from 1 to 2 pm is way overbooked. Not sure this is a good idea. Maybe they’ll move half of those sessions to a fifth slot on Monday? UPDATE: Alan Houser, the STC Summit conference manager, points out that what looks overbooked on Tuesday between 1 and 2 pm are really “concurrent demonstrations in our new ‘Project Showcase'”. So it shouldn’t be a problem… 🙂
2. I’m not affiliated with the STC Summit in any way, in fact, I won’t even be attending. All I did was take data from the summit web site, edit some titles for brevity and rearrange everything into a spreadsheet.

I just thought it would be cool to have something like this and hope it’s useful… 🙂

How to convince managers of topic-based authoring, part 2

To get managers behind a migration to topic-based authoring (TBA), focus on benefits and savings. This is the last post in a two-part series. Find the beginning and background in part 1.

I present the speaker notes and explanations instead of the actual slides which only contain the phrases in bold below.

Benefits and challenges for writers

Make documentation efficient. For technical writers, the structure within topics and across all topics makes writing topics more efficient because you spend less time stressing over what goes where and over layout.

Make documentation transparent. The structure of the topics collection as a whole makes content more transparent: It’s easier to spot a missing topic, if each setup procedure (how to set up stuff) is accompanied by an operating procedure (how to use what you’ve just set up) and by a concept topic (what is that stuff you’ll set up and operate). Thanks to their structure and smaller units, documentation efforts also become easier to estimate – though maybe more tedious to report on in their details.

Collaborate more easily. The structure also makes it easier and faster for writers to collaborate on writing, reviewing and editing each other’s topics, again, because it’s quickly obvious what belongs (or is still missing) where.

Assume new tasks and responsibilities. Challenges for writers are learning a whole new range of tasks and responsibilities, from “chunking” subjects into topics and making sure there is one (main) topic for each subject to interfacing nicely with the topics of colleagues to peer-editing other people’s topics. On the other hand, most writers no longer have to double as layouters and publishers, since that role is usually in the hands of a few people.

Migrating legacy content. Another challenge is, of course, to migrate all existing contents into topics. However, this is a one-time effort, while the benefits of clearly structured topics keep paying off.

Benefits and challenges for companies

Of course, the benefits and challenges for writers affect the company as a whole. But there are additional effects to the company owning topic-based documentation.

Leverage corporate content. Cleanly structured (and tagged) content in topics is much easier to leverage as part of a corporate content strategy. (Did I mention this was a presentation for managers? Hence the verb “to leverage”…) After all, there are other teams who may well hold stakes in some documentation topics or parts of them:

• Product management or even Marketing may want to reuse parts of concept topics, such as use cases.
• Training could reuse procedural topics.
• Quickly searchable documentation can improve customer services – or any type of performance support your company may offer.

Make recruitment more efficient. Clearly structured, topic-based documentation will make it easier on a company to find and hire professional, qualified technical writers – and help new writers get up to speed faster.

Savings from topic-based authoring

Your mileage will vary, depending on your current deliverables, processes and tools. However, from the case studies I’ve seen around the web and at conferences, our numbers are not unusual. Savings are in hours for writers who apply topic-based authoring compared to their earlier efforts without TBA.

• Writing Release Notes as usual – saving 0%
• Writing Online Help, largely reusing Release Notes topics – saving 45-60%
• Writing new User Manuals, by reusing some topics from Release Notes or Online Help – savings unknown
• Updating existing User Manuals, by reusing Release Notes topics – saving 60-75%

Complementary information

To read more about measuring efforts and costs, see my previous posts about:

• How and why to estimate writing efforts
• Top strategies to embrace cost metrics

About topic-based authoring, I recommend these two books:

• Kurt Ament, Single Sourcing: Building Modular Documentation
• Gretchen Hargis, et al., Developing Quality Technical Information, chapter 8 “Organization”, pp. 215-244.

Your turn

Would these arguments convince your managers to support you in moving to topic-based authoring? What other arguments might it take? Should such an initiative to restructure documentation come from writers or managers? Please leave a comment.

How to convince managers of topic-based authoring

To get managers behind a migration to topic-based authoring (TBA), focus on benefits and savings.

Last week, I had the opportunity to present TBA to senior managers. The main objective was to show why it was a good idea to change our documentation method, even though we will have to rewrite and reorganize our contents. Here’s a walk through my presentation. Maybe you find it useful to convince managers – or any non-writers – to support you in implementing TBA.

I present the speaker notes and explanations instead of the actual slides which only contain the phrases in bold below. This post describes the first three slides. The next post within a week will cover the second three slides, so be sure to check back.

What is topic-based authoring?

I use a simple definition plus 5 principles and explain why each of them is important:

Topic-based authoring chunks documentation into topics.

Topics are

• Self-contained, they can be read alone, but stand in context with others
• Task-oriented, they serve users by explaining, instructing or informing (instead of serving the product)
• Reusable (potentially), for example, in online help and manuals
• Output-independent, they can appear online, in PDF or print
• Easy to manage, that is, to write, review, edit, publish, translate (in bundles)

What do topics look like?

An example illustrates the 5 principles in action. I show a screenshot of a rather obvious sample topic of a procedure in the context of the table of contents (a design draft will do, if you don’t have a screenshot). I explain:

• How the topic is self-contained
• How the links to related topics create a context
• How it is task-oriented by instructing the user to do a certain thing
• How it can be reused in the online help and a user manual (online or in PDF)
• How a bundle of conceptual and procedural topics can be processed faster than a complete user manual without losing the context to review, edit and translate it properly

– The main argument, however, is why we need to change and implement TBA. So I have three slides of benefits and challenges, one about each group of stakeholders of the documentation: The customers, the writers, and the owners, that is, our company.

Note that just doing topics forgoes most of the benefits; you need to do them well. This requires a solid structure and tagging within your topics, else you lose a lot of reuse potential. It also requires a well-structured collection of topics where conceptual and procedural topics complement each other, else you lose the transparency of your coverage.

Benefits and challenges for customers

Easier to use. The customers of our documentation are external and internal users alike. For either group, the modular, chunked documentation – if done well – is faster and easier to use, since substantial information has one place and is easy to find under a clear, well-written heading.

More reliable (possibly). As a side benefit, clearly structured documentation may also strike customers as more reliable. To me, it seems that an obviously missing topic is more forgivable than a hard-to-navigate content swamp where you frequently cannot find what you’re looking for. But I have no evidence for this claim.

Harder to read? The challenge to customers can be that it is more tedious to read the documentation front-to-back. Even though we have some manuals today which read like textbooks, that is not our primary use case. So this may be the price for better findability and usability.

More to come…

The next post will feature the second part with the other three topics:

• Benefits and challenges for writers
• Benefits and challenges for companies
• Actual savings from topic-based authoring