Master change – with skills or attitude?

In the face of fundamental changes, skills seem to follow attitude. That’s my second conclusion from Sarah O’Keefe’s webinar about “Managing in an XML environment”. Read on for my summary of her argument and my comments. (Or see my previous post “Top strategies to embrace cost metrics” for more insights.)

Technical writers need a different skill set when moving to structured writing, topic-based authoring or an XML environment, Sarah explained. The general types of skills are the same as when writing “old style” books, such as user manuals: You still need writing skills, people skills, tool knowledge and domain knowledge. But the skills shift focus and application.

Shifting skills

Basically, Sarah argued, you need less tool knowledge and more of the other three skills – and better:

  • Writing skills focus on writing topics and their reuse. Writing topics requires more structure and better compliance to templates than book-like documentation which suffers free-form writing more easily. And topic reuse involves a lot of collaboration.
  • People skills enable increased collaboration. Colleagues may reuse, tweak and add to your topics. In fact, there’s no such thing as “your” topics, once they are subsumed into a larger collection of topics to which several colleagues contribute.
  • Tool knowledge decreases due to the separation of writing and publishing. Yes, you need to learn new tools, Sarah allowed, but that’s an initial effort. Much of the tool effort is split off into implementation and production of the documentation.
  • Domain knowledge steps in to sustain documentation quality. You can no longer hide behind the tools and improve specific parts of the documentation by layout or presentation.

Among all these changes, Sarah said, the biggest challenge is actually to come to constructive collaboration among writers. In a structured environment, the emphasis is on the process of writing and maintaining topics, not on the deliverable end product, such as a manual. Writers share responsibility for topics – which is very different from “owning a book”.

That’s why Sarah urged us not to “succumb to BOSSY, the Book Ownership System SYndrome” and to remember that “CROC is your friend” which stands for “Creating Reusable Objects and Collaborating” (somehow “CROAC” seemed a less appropriate acronym, I guess…).

Shifting attitudes

I agree with Sarah’s premise that topic-based writing requires different skills, with her analyses and her final recommendations. Yet I think the difference she describes is one of attitude rather than of skills:

  • Writing skills are different, not harder. I think it’s just as difficult to write a good, “old style” user manual as writing good topics. Writing topics seems to require more skills, because it’s new and different. I don’t think it’s actually harder, once we writers come to terms with its newness – and our resistance against it, however good reasons we may have.
  • People skills are overdue. I guess we tech writers feel the same pressure as many other professions: To collaborate, to heed stakeholders, to reach out to other teams and to connect to customers. If we notice the pressure more, it may be because we’ve worked in relative isolation. Mastering any change is much easier with a bunch of like-minded people than when you feel alone, stuck in the trenches.
  • Tool knowledge is overrated. Banking on tool knowledge isn’t the best career choice since your job hinges on a tool – and a specific version… When your tasks change, there’s the chance that your tool isn’t the best (anymore) for what you need to do. Tech writers should be really good at wrangling content (props to Scott Abel), not tools. If you distinguish methods and tools, I think you’ll find that it’s much faster to learn a new tool than to learn a new method, such as topic-based authoring.
  • Domain knowledge is second to content proficiency. While one can never have too much domain knowledge for a job, our key skill is to structure and relate that knowledge. I firmly believe that you should “always hire the better writer“, for two reasons:
    1. It helps your corporation to build up complementary skills: Your corporation probably has lots of domain specialists already – but how many really good writers does it have?
    2. In my experience it takes a year or two to become a decent domain specialist – but it takes longer than that to become a decent writer. (Though your mileage may vary…)

That’s why I come to a different conclusion. How successful we tech writers are when changing to a environment or processes depends less on our skills, but more on our attitude to them. There are at least two different ways we tech writers can regard our deliverables, our writing skills and our tool knowledge:

  • If they are our assets and define what we do, any change in environment and processes will threaten us.
  • If they are the results of previous learning, we can embrace change with the confidence that we can rise to the challenge again.

For example, when I feel I own a manual, any review, any editing has serious crisis potential already. I know what it’s like, I’ve been there… But once I feel shared reponsibility for the documentation at large, it takes on a more constructive, larger dimension, where we’re all in it together. Well, most of us, anyway… 🙂

Your turn

What determines how you face change: Your skills or your attitude? Can training and skills ensure buy-in for a new environment or processes? Or is it more important to have a self-confident, competent attitude?


Top strategies to embrace cost metrics

Moving to a structured writing environment can change the metrics of documentation. That’s one of the lessons I learned in a great webinar by Scriptorium‘s Sarah O’Keefe about  “Managing in an XML environment”.

If you’ve missed it, check out the 45-minute recording/slideshow on their website. You’ll find it very interesting, if you’re wondering what it will be like to create and maintain documentation, once you have implemented XML. I’ll summarize a few aspects that I found interesting and comment on them.

XML increases transparency

Creating documentation in an XML environment increases the transparency in writing documentation, for better or worse. Tech writers’ work in XML is more visible earlier in the process: Without XML, a writer may deliver a print-ready PDF after months. With XML, she might check in topics every day for a nightly build.

Just as content gets chunked from books to topics, so progress gets chunked from weeks and months to hours and days. What can be measured often will get measured, so Sarah warns: Beware of seductive metrics. Measuring pages per day, for example, is silly: It will increase page count, but not necessarily the quality or the effectiveness of the documentation.

Strategy #1: Learn to QUACK

Measure something useful instead. Sarah suggests the QUACK quotient:

(quality + usability + accuracy + completeness + “konciseness”) / cost

Sarah goes on to define each of the five “QUACK” factors in similar terms as Gretchen Hargis, et al. in Developing Quality Technical Information. For example, quality considers whether the documentation is well-written and well-structured. “Konciseness” (spelling follows acronym as form follows function) means to provide as little documentation as is necessary, but no less. This improves efficiency for users and localizers alike.

I think this approach is great for scenarios where you can’t get out of cost metrics. Using accepted quality criteria is definitely better than being held to junky metrics.

But I wonder how quantifiable the five dividends actually are: How accurate is a topic? “Very accurate”, if I’m lucky – but I wouldn’t know how to put a number on that… Also, each dividend should be weighted according to audience and industry, Sarah explains. For example, completeness of documentation is more important in regulated industries than video games. That doesn’t make the quantification any easier or less contested.

Strategy #2: Duck the cost

My own strategy requires even more leverage for tech writers than just pushing a new formula through to assess our work. So it probably doesn’t work for all tech writers.

The QUACK quotient takes for granted that documentation is a cost center. Of course, many managers share that view. But I wonder if we tech writers wouldn’t be better off, if we got out of that defensive corner altogether.

I think it helps us more in the long run to show how documentation contributes to the larger corporate processes of production and value added. So I suggest that it’s worth to argue along these lines:

  • Turn transparency into cost attribution: Show how each topic’s cost can be counted towards the development cost of the feature or part that it describes, just like other stages in the production processes. It’s like applying total cost of ownership to your own products.
  • Turn topic reuse into corporate efficiency and assets: Show how reused topics create extra value or reduce costs in other departments, for example, in training, customer services or marketing.
  • Measure relative cost savings: Show how writing XML-based documentation is more efficient than the previous non-XML process, once you’ve overcome the initial hurdles.

Bonus link: Cost metrics white paper

If you’re into DITA or want to see how cost metrics for structured writing break down to actual numbers, check out Mark Lewis’ clear and thorough white paper “DITA Metrics: Cost Metrics“:

You’ve already concluded that moving to DITA will save you tons of time and money. But management says prove it. This paper helps you determine the cost portion of the ROI calculation. What are my costs now? What will my new costs be with DITA? And what is the difference—my savings?

Your turn

What do you think is the best way to justify tech writing cost? What scenarios or strategies have you seen succeed or fail? Share your thoughts in the comments.

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

Truly helpful help systems are more than a set of instructions and information. They offer a constructive, pleasant user experience that make users happy and efficient. Which makes help systems comparable to libraries or department stores…

David Weinberger has an interesting analogy how information systems in general are like – and unlike – retail stores in the beginning of his book Everything is Miscellaneous. You can read the prologue and chapter 1 online.

Here are 10 things that users want to do in a help system – or a library or a department store… Some of them are kind of obvious, but I think it helps to consider all of them and how they relate to functions and options in a help system. Which ones you want to offer depends on your users, your product and your tech writing resources.

1. Search

I know exactly what I’m looking for.

Offer useful search results. Duh…

2. Find (and find again)

I know it should be here somewhere. I swear I’ve seen it last time!

Offer filter options to narrow down search results by topic type, task type, persona, etc., so users don’t have to guess how your topics are structured or how to rephrase their search. Allow users to save search result lists and to bookmark favorite topics.

A good discussion how users search and find in different ways is in Morville’s and Rosenfeld’s book Information Architecture for the World Wide Web, chapter 3 “User Needs and Behaviors”.

3. Know their way

I know where it is… – Now how did I get here? How do I get back?

Offer navigation aids such as a table of contents, browsing sequences and breadcrumb trails, so users can

  • Explore topics in context,
  • Look up their current location in the system,
  • Backtrack their steps.

4. Browse (as in “shopping”)

I’ll know what I want when I see it.

Offer tags that describe and group topics, so users can quickly get to the right section and dive in.

5. Get advice

I don’t know what I need. This is all new to me.

Recommend tutorials, best practices, what’s new, tips & tricks to guide novice users – and visitors who wonder about the learning curve of your product.

6. Recognize items

What is this thing? What does it do? The box doesn’t say.

Offer clear and, if possible, unique topic headings so users are confident they’re looking at the appropriate item.

7. Compare

This isn’t quite what I’m looking for… Do you have something similar?

Offer a selection of related topics.

8. Ask a human

What does this mean? I don’t understand this. This doesn’t seem to work!?

Offer options to send an e-mail, or a request for service, callback or chat to your company.

9. Share

This is cool! Here’s my comment. My friend/colleague should see this!

Offer ways for users to submit feedback, comments, ratings. Allow users to e-mail or tweet a topic.

10. Take stuff home

I’ll take this!

Allow users to print or make a PDF of one or several topics.

Your turn

Which use cases do you find essential? Have I missed any? Or could you do without most of them as long as your search rocks?

Help smash tech writing dogmas!

I confess: I have a couple of dogmas about tech writing – though I generally consider them detrimental to communicative, collaborative jobs such as ours.

By dogma, I mean here a firmly held belief that I assume applies universally, if only because I haven’t been convinced otherwise yet… 🙂

However, seeing how much I’ve learned from your great comments and opinions to my previous posts, I’d like to invite you to chip away at my preconceived notions. Maybe my dogmas are unfounded and silly…

So here goes, meet two firmly held beliefs that I’ve acquired over the years:

Don’t build your own HAT!

I don’t care how cool you are as a software company, I firmly believe that you should not build your own help-authoring tool (HAT), unless that is actually (part of) your business.

True or false? I believe it’s true: The initial project to build the thing is like reinventing the wheel, but you may actually get all the cool features you think you need and don’t get from a third-party system.

But I’ve yet to see a company that can sustain the required maintenance efforts: Development for profit goes before development for internal cost centers, and just about anything goes before documentation. So dev resources for the HAT are always scarce and low-priority. As a result, bug fixes, updates and enhancements to the HAT take longer than they should. Meanwhile, writers work inefficiently and with frustration which often brings down the quality of the help.

I also doubt it makes economical sense to continuously invest non-billable development time when you can get a third-party product and maintenance plan, usually for a fraction of the cost.

Don’t buy a tool to fix your processes!

Blame your tools all you want for why your documentation is bad and/or painful to create, I firmly believe that getting a new tool won’t fix that.

True or false? I think it’s true: Frequently, bad tools beget bad processes, but you need to fix your processes separately. Problems with the tool can be so obvious, they tend to obscure ill-designed processes.

Actually,  I recommend to fix the processes first, so you can then buy the right tool that supports them. A good tool makes it easier and more efficient to create good results, but good pots and pans don’t make you a master chef.

Have at it!

Please help out a fellow tech writer: Leave a comment and give some reasons, if you think:

  • Dogmas deserve to die, and these especially!
  • Dogmas are generally bad, but these are actually true!
  • Dogmas rule, and we need more of them!