Top 5 tech writing posts in 2011

Here are the 5 most popular posts on Kai’s Tech Writing Blog in 2011. After my Top 3 tech comm lessons, this is the second “year in review” posts.

Kai’s Tech Writing Blog takes a break now and will be back in 2012. I thank each one of you for reading and commenting; I’m happy and proud to be part of such a stimulating professional community, and I’m a better tech writer for it!

5. 2011 megatrend in technical communications

In January, I mashed up three predictions by Sarah O’Keefe into one megatrend:

I think this year’s megatrend for technical communicators and their managers, especially employed ones, is to position tech comm as a business in its own right – or to be redundant in the long run.

4. Learn about DITA in a couple of hours

I still think the best way, if you have two hours, is to read Ann Rockley’s DITA 101, second edition, which I reviewed:

The book excels in firmly embedding DITA’s technologies and workflows in the larger context of structured writing and topic-based authoring. … I recommend that you read it if you are involved in a project to implement DITA, writing or translating documentation in a DITA environment or managing technical writers

3. Improve documentation with quality metrics

This is my only post this year with a visual cue inspired by a Marx Brothers’ movie! 🙂

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.

2. 5 steps from legacy documentation to topics

The company I work for set off to migrate its documentation to topic-based authoring:

To move to topic-based authoring, you need to convert existing documentation into topics. The efforts shouldn’t be underestimated, but it’s actually a pretty straightforward process. I’m describing how to convert sections in manuals, but it’s much the same for most content, whether it’s FAQs, wiki articles, training materials, etc.

1. Top 4 benefits of writing a tech comm blog

As I entered my second year of blogging, I reflected on the reasons and benefits of Kai’s Tech Writing Blog:

1. Improve ideas
2. Connect with the community
3. Picture progress
4. Write regularly

Your turn

What was your favourite tech writing blog post, on this blog or elsewhere? Feel free to leave a comment.

Advertisement

Art vs. online: 2 dimensions of curating

Curating is a cool word, or trendy jargon, for what happens in web technologies and in art museums, but they are fundamentally different activities.

In this post, I want to add an alternative view to Rachel Potts who recently wrote about “When software UX met museum curation“. Where Rachel emphasises similarities, I’d like to focus on the differences, especially as they relate to art museums.

Your artefacts

One serious limitation and difference in curating at art museums, compared to anything in software and online, is that you need to care for original, unique works. If you mount a special exhibition, you need to procure them to begin with. And sometimes you cannot get them, no matter how much you want them in the show to present an artist or an era in history or to make your case.

• Some works don’t travel because they’re fragile or because the insurance is too costly or because they’re centerpieces in the collection that owns them.
• Some owners won’t lend works to you, because you cannot satisfy security requirements or because you’re too small a museum or because they don’t like your director.
• Some works are simply lost.

Of course, you can always do with fewer or lesser works or, in the case of historic artefacts, with copies, but that invariably hurts the critical response and your attendance.

"Stalking Christina" - other people regarding my favorite painting

Your objectives

Another difference is that for many art museums “enabling users to learn” is one objective among many. And several other objectives are, unfortunately, at odds with it:

• Some pieces are too sensitive to light or touch or movement to allow more than very few people to experience them.
• Some museums need to please or placate donors (who may influence what’s shown and what not) and trustees (who may influence what gets paid for and what not).
• Some museums don’t have the means: They lack the manpower to accommodate visitors more than a few hours per week. Or they don’t have the expertise to allow them to learn well.

Your audience

A third difference is that art museums who put on ambitious, critically well-regarded exhibitions find that attendance is surprisingly low. The reason is simple and disappointing: Many people don’t want to be enabled to learn in art museums. They don’t want to learn new things, much less have their beliefs challenged. Instead, many people visit an art museum, because of the way it makes them feel:

• Many go to be in the presence of beauty or to be awed. Hence the success of any show whose title mentions a best-selling artist or any of the words “Impressionist”, “Gold” or “Gods” – even if the title is far-fetched and the show mediocre at best. “Dinosaurs” gets kids, and anything that flies or shoots gets their dads.
• Some go to feel cool. Hence the success of after-work parties in modern art museums.

The words

Roger Hart once told me, it’s futile to try to stop linguistic change. And the web is a great change agent of language:

• How many kids today know that women warriors (or a river) gave their name to an online store?
• The German language has known about “email” for centuries (though we only spell it thus after a recent change in orthography); in English, it’s known as “enamel”.

But if language is to represent the real world, I advocate to respect the differences within one word, such as curating. Conflating two similar activities into the same word cheapens our experience of the stuff that surrounds us.

Tech comm meets content strategy, with Ray Gallon

Technical communications and content strategy have a lot to say to each other.  Bloggers have frequently related the two disciplines. Tech comm conferences run streams on content strategy, for example, tekom11 dedicated a whole day to the topic.

Content strategy for software development

Ray Gallon at tekom. Photo by @umpff, used with permission.

Leave it to Scriptorium and their excellent webinars to shed some light on the situation. Recently, they invited Ray Gallon to present his “Content Strategy for Software Development“. (To learn more about Ray, read his recent interview over at the Firehead blog. Or you can check out the very similar presentation which Ray held at tekom.)

Ray’s presentation was very enlightening to me, because he applied content strategy to software development. I create documentation for software applications, so I can relate to creating content for them. In the following, I’ll mainly focus on the first half, but I recommend watching the entire webinar.

Software development as information-rich environment

For the sake of his argument, Ray set the stage by looking at (complex) software developments not as products or tools, but as information-rich interactive environments. Software could thus be an expert system that supports users to make an appropriate decision, e.g., a medical diagnosis.

The first question to content strategists is then: What does the user need from the software? There are several answers; the user may need to

• Know something (relating to concept topics)
• Do something (relating to task topics)
• Explore or understand something
• Integrate or combine the software with his other tasks and processes

Plan to help your users

Ray then presented several document types which help content strategists to plan how they can best support users in their tasks and decisions. Among them was the Content Requirements Worksheet:

Ray Gallon's Content Requirements Worksheet explained. Click to enlarge. (Pardon the mediocre quality; prezi > WebEx recording > SlideShare is one compression too many...)

This document was a real-eye opener for me. It represents a holistic view of all user-facing content in a software application:

• Informational, editorial content
• Structural software content, such as user interface messages
• User guidance, such as tool tips, help screens
• User decision support to help users do the right things for the right reasons
• Dynamic content, such as search results
• Live interactive content as preesented in forums and social networks

Content workers, unite!

The Content Requirements Worksheet can be very beneficial to future users of a software. But it presents a challenge to content strategists to get a wide variety of requirements right. That is the opportunity for technical communicators and user experience designers and information architects to pool their skills and join forces.

As Ray said in his comment to my previous post:

Many tech comms do a bit of, or a lot of, content strategy in their work, and if an organization has a content strategy then everyone, tech comms included, needs to understand it and be on board.

So let’s transcend the silos of our systems, their manifold features and the artefacts we’re used to creating. Let’s start with good, thoughtful design from which our users benefit.

Your turn

Is this a good way to relate content strategy to technical communications? Or do you know better ways? Feel free to leave a comment.

All aboard! Onwards to structured authoring!

Our team of technical writers is embarking on a journey towards structured authoring. With 10 writers, we’ll move from an unstructured Word to PDF/CHM environment to a structured Flare to WebHelp/PDF environment. Or I should say “semi-structured”: We do have an information model based on DITA, but we won’t actually be able to enforce it with Flare (which we knew before we chose the tool).

It’ll be an interesting cruise, to be sure! Four writers already apply topic-based authoring rather than the previous free-form documentation guided mainly by common sense. The others have had training, but no real opportunity to write topics continuously. We have drafted tighter new processes to draft, write, review and edit topics to replace the previous loose processes of writing and reviewing, but they are not in place yet.

And then there’s the new tool, of course. Only one of us has worked with Flare before. Many of us are excited about getting Flare. Some really like it – what we’ve seen in several demos so far. Others just really loathe the current writing environment.

“Regarding the pain of others”

So as we’re about embark, I’ve been looking out for others who’ve taken the trip before. Scriptorium’s State of Structure webcast has been very helpful: Its results of a survey among 200 tech communicators helps to position us in relation to others who are currently implementing structured authoring or considering it. It also collects some mistakes respondents have gone through. I’ll just be quoting a few select points, but the whole webcast by Sarah O’Keefe is totally worth checking out, so thanks to Scriptorium for making this webcast available!

Reasons

The top reasons why survey respondents (consider to) move to structured authoring made us nod emphatically: Reuse, consistency and cost savings are also at the top of our wish list of achievements. Looking ahead, it’s promising that the majority of respondents achieve these goals.

We’ll also take other goals that respondents achieved, whether it’s to automate processes or to reduce content (oh, yes, please, we’re not even exactly sure how much redundant, almost identical content we have). So far we’re confident, we’re not only doing the right thing, but doing it for the right reasons, too!

Efforts

Savings have their own price, of course. Sarah’s survey confirms several cost points we’ve already identified in the project.

• Converting legacy content is a biggie for us, simply because we currently have a lot of stuff.
• Redefining output layout will take time, but will be worth it given what Flare is capable of doing with CSS in both web and print outputs.
• Integrating a new system with its writing and publishing processes into our product and workflow systems will also take some time.

Mistakes

Mistakes have been made by others before us, and we’ll have plenty of chances to make our very own mistakes. If we’re lucky, we can avoid repeating the mistakes of others:

• Planning and project management cause problems, maybe because most companies lack the experience of major documentation overhaul projects. Sarah specifically mentioned the lack of understanding of the project scope and of the need for testing. So we’ll look through our project plan again and ensure that the estimates are plausible.
• Converting legacy contents can also get you into trouble, especially when you convert something that’s less than structured. It doesn’t help if you reserve too little time to do it or get inexperienced people to do, whether it’s off-shore labor or student helpers. That’s sound advice: GIGO (“garbage in, garbage out”) can certainly endanger the expected benefits. A new tool can help us be more efficient, but we still have to learn and apply structured writing in topics. So this confirms one of my two tech comm dogmas: Don’t get a new tool to fix your processes!

Setting out

What do you think? Is our crew well-equipped, given a tried and proven method, well-defined processes, a new tool and the words of warnings above? If you have additional advice, please leave a message.

When redundancy is good: Online help navigation

Redundant navigation can help users find what they’re looking for.

Redundancy in documentation is usually bad: When you have the same content (in different words) in two places, you pay twice for localization – yet you probably only remember to update one of the items. So you risk inconsistencies, extra costs and general havoc.

Not so when it comes to navigation! Redundant navigation can offer your users different paths to get to the one place where they find what they need. The reason this works is because users want to do different things at different times in your help system. (See my earlier post “Top 10 things that users want to do in a help system“.)

Tom Johnson’s recent post got me thinking about this when he asked for “Examples of Help Systems that Provide Users with Multiple Entry Points?” His approach is a bit different, however, from what I have in mind. Tom thinks about “adding metadata to help topics so you can sort them into different arrangements for different audiences”.

My idea is to offer a few additional entry pages with layers of pointers to get users to the appropriate part of the help system quickly. Only some of the options require tags on topics.

Here’s a design I once did for the rather comprehensive online help navigation of an asset management system, we’re talking several thousand topics. (Click on the image for a larger version.)

The idea is that different personalities of users come to the help with different kinds of questions:

• Some users focus on their roles and approach the system from that angle, whether they work in front, middle or back office of a bank or asset management company.
• Other users focus on the task they need to execute – which in an asset management system can be boiled down to five main types of tasks.
• And some users expect to find certain forms of documentation, such as release notes, tutorials, manuals.

Depending on your choice, you would get through 1 or 2 more selection screens until you wind up at a specific help topic. And you could take different paths to get to the same topic.

For example, if you wanted to set up a fund, you would need to get to the topic “Set up a fund definition”. Of course, you wouldn’t know that. But you could get there in various ways.

For example like this:

1. I’m working in: Back Office
2.  > Fund accounting
3.  > I need to set up fund accounting
4.  > Set up a fund definition

Or like this:

1. I want to: Set up static data
2.  > For a fund
3.  > Set up a fund definition

Or like this:

1. Show me: Tutorials
2.  > How to set up SimCorp Dimension
3.  > Fund accounting
4.  > Set up a fund definition

So the idea is to anticipate some of the most common questions and approaches users have to the system and to make the right entry points easy to find. This does not to offer so many paths through the forest of topics as to confuse users, but only signposts to topics we expect every user will hit (as long he is using a particular module at all.

Your turn

Could you, would you use such a help portal that offered different paths or would you bypass it in favor of the tabel of contents on the left and the search? Do you know other help systems that use such a structure? Please leave a comment.

How (not) to use documentation checklists

Checklists can be great aids, but they won’t guarantee that you create good and complete documentation. – That’s my experience, and I’d appreciate your input whether you agree or not.

The Valuable Content Checklist

Content strategist Ahava Leibtag published the “essential Creating Valuable Content Checklist (TM)” last month, along with a step-by-step guide:

With this checklist, you can ensure that your web content is

• Findable – because it has a headline, title, keywords, links, etc.
• Readable – because uses chunking, bulleted and numberes lists, etc.
• Understandable – because addresses user personas and their proficiencies, context, etc.
• Actionable – because it gives readers incentive to act, comment, share, etc.
• Shareable – because it gives readers a reason and the means to share, etc.

I think Leibtag’s checklist covers a lot of essential features of good documentation, so it should also work well for technical communications. (The book Developing Quality Technical Information by Gretchen Hargis, et al., also contains great checklists for documentation.) But then I had second thoughts…

Clear and simple

The good thing about checklists is that the best ones are clear and easy to use. They remind you of things you may forget otherwise. One of the most impressive recent examples of their benefits has been in medicine: Peter Pronovost’s checklists have shown to improve the delivery of critical care. (Atul Gawande reports on them in the New Yorker of 10 Dec 2007.)

Seductively simplifying

The bad thing about checklists is that they are so clear and simple, it can be seductive to rely on them for things they cannot do. You can check off all items on your checklist, but you may still create

• Incomplete documentation, when you’ve missed a sub-topic, keywords, links, a persona or a use case.
• Useless or bad documentation, when you describe an unintended or even dangerous way of using the product.

In other words: You get what you measure. If checklists are your tool, you will get formally complete documentation, which may or may not be helpful to customers.

As simple as possible, but no simpler

I think the solution lies in the quote attributed to Albert Einstein: “Everything should be made as simple as possible, but no simpler.” That’s good advice for documentation in general, and for checklists in particular. This means to me:

• Use checklists only after writing a topic to verify that it satisfies formal completeness standards.
• Avoid checklists while writing a topic when I focus on content and quality, specifically on usefulness and applicability for users or personas.

I also appreciate that structured writing already separates layout and content, so I can use my “freed-up brain cycles” to focus on content and not go on auto-pilot and simply fill in topics with bits and pieces while ticking off check boxes.

Your turn

Do you think checklists do more good or harm in technical communications? How do you use them to make sure they improve your documentation, but don’t compromise it? Please leave a comment.

@techwriterkai popular posts, part 2

My blog is taking a spring break 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 makes 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:

Top 3 success factors in online help systems

… in which I apply usability tips based on research to online documentation and come up with three success factors: Speed, structure, and spacing.

Top 10 reasons for tech writers and trainers to collaborate

… in which I explain why and how technical communicators can and should collaborate with trainers to offer customers a unified and cost-effective learning experience.

Ragged-right or justified alignment?

… in which I argue for the preference of ragged-right over justified alignment in print and point to several sources where research supports the argument.

Bonus insight

Buzzwords in post headings do work: Of my all-time top 10 posts, four are “Top X something” and two include the word “trend” in the heading…

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)? Feel free to leave a comment!

@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!

Recommended read: Degree helps tech writers

Here’s an example of how graduates of a tech comm program put their skills to use in a high tech company.

Specifically, National Instruments at Austin contributes two guest posts to the Texas Tech STC Student Chapter blog. Yes, these are recruiting posts, but they do ring true. I think they reflect well how a company can take tech comm seriously and benefit from the formal training and academic skills of graduates. It may be an exception among the employers of tech writers, but it’s an encouraging example. So I recommend these two posts:

Tech Writing…It’s Not Just For Tina Anymore
… asks Texas Tech alumni who now work as tech writers and their managers how they can apply what they’ve learned and what advice they have to students and prospective employees:

• Rayo emphasize task analysis before tool skills – which I’m glad to hear.
• Robin gives SME interviews a reality check that strikes a balance between what’s desirable and what’s possible.
• Heather explains how she determines which documentation formats get produced.

Technical Writing Skills
… has Nathan Stokes list and explain 5 skills which every tech writer can benefit from – especially in this less than obvious combination:

• Editing, including yourself: If you can edit yourself, you’ll be a better writer.
• Productivity, i.e., project management skills to keep yourself organized.
• Enthusiasm
• Curiosity, which can drive you and help you to grow.
• Computer Knowledge

– Previously in these pages, I’ve covered a how a (non-tech comm) degree can help a tech writer.

Your turn

Are these skills useful in the tech writer workplace? Can you learn them – or at least expect to learn them – in a tech comm program? If you have any thoughts or experience, please leave a comment.

Improvements in Kai’s Tech Writing Blog

I’m now maintaining a page about past and upcoming articles and conferences called Elsewhere. It’s always available via the header tab.

And I have new header photograph which a couple of readers have asked about: I have a passion for the American Southwest and like to hike its deserts and mountains. The picture shows springtime in the Huachuca Mountains of southeastern Arizona. The view is from Coronado Peak looking east towards the San Pedro river valley. Walk off to the right/south for a couple of miles, and you’re in Mexico.