Getting ahead as a lone author, the article

“Getting ahead as a lone author”, based on my presentation in last September’s TCUK conference, appeared as a 3.5-page article in the current Winter 2010 issue of ISTC’s Communicator.

Click the cover to download the article in PDF.

Click to download the article in PDF.

I’ve covered lone authors over the last months in blog posts and in my presentation, after which Katherine Judge, commissioning editor of ISTC’s quarterly, asked me to write it up as an article which I share with you today.

It’s a concise summary of my talk, along these headings:

  • Overcome benign neglect
  • Buy yourself time
    • Implement topic-based authoring
    • Don’t test when you should be documenting
    • Learn to say ‘later’ and ‘no’
    • Control interruptions
  • Treat documentation as a business
    • Make documentation an asset
    • Estimate documentation effort
    • Plan documentation properly
    • Embrace reporting and metrics

2011 megatrend in technical communications

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.

This is my conclusion after thinking about three astute predictions that Sarah O’Keefe recently blogged about.

– I know: I’m late to the predictions party. And I’m actually not very good at crystal ball gazing. I’m much better at reconfiguring what I find. So my contributions are comments and some additional reasons why I think Sarah’s right.

Three sides of the same coin

If you’ve read Sarah’s post, I’ll just remind you of the headings of her predictions:

  • A schism in tech comm (traditional vs. modern tech comm)
  • The age of accountability
  • Increased focus on business value

If that doesn’t ring a bell, head on over and read her post, I’ll wait… 🙂

I think Sarah’s predictions are really three sides (?) of the same coin. And I’d be surprised to see a documentation team experience only one of them.

Business value

The lackluster attitude about documentation of “No one reads it, but you gotta have it” has been widely replaced by close scrutiny of its value add and ROI. I’ve recently seen a doc team’s initiative that had to present the same business case, including cost saved and break even, as any other internal initiative that wanted to spend some money. But more is at stake for us writers than playing the numbers game with managers and bean counters.

The question is how the tech comm team is perceived: As a cost center or as contributing to the corporate assets. The latter is of course more desirable and can only succeed when we break down departmental silos, when collaborate with other teams and become user advocates, see my earlier comment on Scriptorium’s blog.

Now take a step back and think of what that cost vs. asset question means to your job and your career outlook. To me, it’s awfully close to being seen as part of the problem or part of the solution…

Another reason why I think tech writers do well to consider and promote their business value is…

Accountability

Sarah’s second prediction follows directly from attention to business value: Once a company expects ROI from documentation, it will want to monitor the output. And that means to hold the documentation team accountable, not by measuring the quantity of produced stuff, but by measuring the quality of useful assets that have been efficiently produced. (It’ s worth keeping in mind the difference between accountability and responsibility; link courtesy of Jurgen Appelo and his presentation on authority and delegation.)

In the metrics, you may have some leverage: If you’ve ever tried it, you’ll find it’s awfully hard to come up with reliable metrics for documentation quality. The good news is that your managers will usually find it even harder. That’s a chance for you to apply some “Top strategies to embrace cost metrics” .

If you’re alert and on top of your game, you’ll find you have some agency in how you’re measured. It won’t always be your choice alone, but to a certain extent, you can choose sides in…

The schism in tech communication

The distinction looks crude, but I’ve found that many technical writers fall into one of the two camps that Sarah has identified:

  • “Traditional tech writers” who produce communication deliverables, such as user manuals and online help.
  • “Modern tech communicators” who provide user assistance services as part of the customer experience.

Note that this distinction has nothing to do with quality! I know very diligent, highly qualified people in both groups, and I’ve seen sloppy work in conventional manuals and modern screencasts.

I believe how that schism plays out for each writer in a team has a lot to do with the accountability of the documentation team, the responsibility of the team members and the dynamics between the members: Ideally, both types complement each other – and can show management that they are strong and agile because of their complementary strengths.

Now what?

Okay, so treating your documentation as a business before everybody else does sounds reasonable. For specific next steps, may I recommend the slides from my TCUK presentation “Getting ahead as a lone writer” and my other blog posts for lone writers. Even if you’re not a lone writer, you’ll find many ideas also apply to documentation teams.

Your turn

What do you think? Are these trends part of a larger movement to economize and commodify technical writing? Or is it nothing new, not worth beating a dead horse over? Please leave a comment.

Learn about DITA in a couple of hours

DITA 101, second edition, by Ann Rockley and others is one of the best tool-independent books about DITA. It’s a good primer to learn about DITA in a couple of hours.

Strong context

The book excels in firmly embedding DITA’s technologies and workflows in the larger contect of structured writing and topic-based authoring.

DITA 101, 2nd edition, cover I attribute this to the authors’ years of solid experience in these areas which comes through, especially in the earlier chapters.

“The value of structure in content,” the second chapter, illustrates structured writing with the obvious example of cooking recipes. Then it goes on to show you how to deduce a common structure from three realistically different recipes – which I hadn’t seen done in such a clear and concise way.

“Reuse: Today’s best practice,” the third chapter, takes a high-level perspective. First it acknowledges organizational habits and beliefs that often prevent reuse. Then it presents good business reasons and ROI measures that show why reuse makes sense.

Comprehensive, solid coverage

From the fourth chapter on, Rockley and her co-authors describe DITA and its elements very well from various angles:

  • “Topics and maps – the basic building blocks of DITA” expands on the DITA specification with clear comments and helpful examples.
  • “A day in the life of a DITA author” is very valuable for writers who are part of a DITA project. Writing DITA topics and maps is fundamentally different from writing manuals, and this chapter highlights the essential changes in the authoring workflow.
  • “Planning for DITA” outlines the elements and roles in a DITA implementation project for the project manager. Don’t let the rather brief discussion fool you: Without analyzing content and reuse opportunities, without a content strategy and without covering all the project roles, you expose your DITA project to unnecessary risk.
  • “Calculating ROI for your DITA project” has been added for the second edition. It’s by co-author Mark Lewis, based on his earlier white papers: “DITA Metrics: Cost Metrics” and “DITA Metrics: Similarities and Savings for Conrefs and Translation“. It expands on the ROI discussion of chapter 3 and creates minor inconsistencies that weren’t eliminated in the editing process.
  • “Metadata” first introduces the topic and its benefits in general and at length. Then it describes the types and usefulness of metadata in DITA. This might seem a little pedestrian, but it’s actually helpful for more conventional writers and for managers. It ensures they fully understand this part of DITA which drives much of its efficiencies and workflows.
  • “DITA and technology” explains elements and features to consider when you select a DITA tool, content management system or publishing system. This always tricky to do in a book as much depends on your processes, organization and budget. While the chapter cannot substitute for good consulting, it manages to point out what you get yourself into and what to look out for.
  • “The advanced stuff” and “What’s new in DITA 1.2” continue the helpful elucidation of the DITA specification with comments and examples that was begun in the “Topics and maps” chapter.

Mediocre organization

For all its useful contents, the book deserves better, clearer organization!

  • Redundancies and minor inconsistencies occur as concepts are defined and discussed in several places. For example, topics are defined on pages 4, 24 and 46. The newly added ROI chapter complements the ROI points in the third chapter, but neither has cross-references to the other.
  • The index doesn’t always help you to connect all the occurrences and navigate the text.
  • Chapters are not numbered, yet numbering of figures in each chapter starts at 1. It’s not a big problem, because references to figures always refer to the “nearest” number, it’s just irritating.

Formal errors

The book contains several errors which add to the impression of poor production values. They don’t hurt the overall message or comprehensibility, but they are annyoing anyway:

  • Mixed up illustrations such as the properties box in Word (page 72) vs. the properties box from the File Manager (73)
  • Spelling errors such as “somtimes” (1) and “execeptions” (16)
  • Problems with articles such as “a author” (20) and or a system that “has ability to read this metadata” (77)
  • Common language mistakes such “its” instead of “it’s” (52)

Lack of competition

Another reason why it’s still one of the best books on the topic is that there simply aren’t many others!

  • Practical DITA by Julio Vazquez is the only serious contender, and its practical, in-the-trenches advice complements Rockley’s book very well.
  • [More books are pointed out in the comments, thanks everybody! – Added January 11, 2010.]
  • DITA Open Toolkit by “editors” Lambert M. Surhone, Mariam T. Tennoe, Susan F. Henssonow is a compilation of Wikipedia articles. Amazon reviewers call other titles produced by the same editing team and publisher a scam.

Of course, several other honorable and worthwhile books include articles or chapters on DITA and/or discuss DITA in context of specific tools.

My recommendation

Despite its shortcomings, the book’s own claim is valid: “If you’re in the process of implementing DITA, expect to do so in the future, or just want to learn more about it without having to wade through technical specifications, this is the book for you.”

I recommend that you read it if you are

  • Involved in a project to implement DITA
  • Writing or translating documentation in a DITA environment
  • Managing technical writers

Your turn

Have you read this book? What’s your opinion? Can you recommend other books or resources about DITA? Feel free to leave a comment!

How efficient is your documentation?

To gauge the efficiency of your documentation, consider the time spent to create it plus the time it takes to use it.

That’s the lesson I learned from applying Scott Berkun’s make vs. consume ratio to documentation. Scott’s idea is generally that it takes time A to create a tweet or a poem, a book or a movie, and time B to read or watch it. Scott relates the two measures and points out how you can easily consume in a few hours what authors and publishers, actors and movie people have spent months fabricating.

“make + consume” in documentation

When it comes to documentation, I think you can add both measures to gauge efficiency of documentation – though not its coverage or quality!

But just for time, I try to keep in mind these tactics:

  • Minimize the total time required for you to create your documentation and for customers to find, use and apply it.
  • Consider spending more time to make your documentation faster and easier to use, especially if you find that customers have trouble with it.
  • Consider spending less time with documentation tasks that do not help your customers in using the described product.

Of course, time isn’t the only yardstick. Accuracy, completeness, legal and contractual obligations are just some of the other factors.

Still, I’ve found “make+consume time” a useful benchmark to stay focused on what ultimately benefits the user and what doesn’t.

Further reading

If you’re concerned about documentation efficiency, you might also find earlier posts of interest:

Your turn

How do you gauge the efficiency of your documentation process and output? Can you credit your efforts towards making your documentation faster and easier to use? Please leave a comment.

Top 10 reasons for tech writers and trainers to collaborate

Technical writers can and should collaborate with trainers to offer customers a unified and cost-effective learning experience. Here are eight specific reasons why they should collaborate – and two why they cannot afford not to do it:

  1. Same goal: Ensure that customers can set up and operate the product efficiently, effectively and confidently.
  2. Same audience:  Customers, more specifically users of the product (who, in a corporate setting, may have made the decision to use it or not).
  3. Same demands by that audience: Fill a knowledge gap, whether it’s large or small, conceptual or practical.
  4. Similar deliverables: Conceptual and instructional/procedural information, possibly in different formats, such as training slides or handouts, user manuals or online help.
  5. Cost-effective deliverables: Share text and images, use cases and examples.
  6. Better coverage: Writers and trainers see the product and its users from different angle and can help avoid professional myopia.
  7. Beneficial reviews: Writers and trainers who review each others work also learn about their own deliverables.
  8. Satisfied customers: A unified learning experience increases user confidence, satisfaction with and trust in the product.

Companies where writers do not collaborate with trainers run a considerable risk:

  1. Confused customers: Incoherent or even contradicting messages in documentation and training materials confuse and alienate users.
  2. Lost business, potentially in three ways:
    • Bad reputation and bad impressions keep prospects from buying.
    • Bad learning experience keeps customers from continuing or returning to the product.
    • If you’re really big, external companies can take a bite out of your training or manual business.  This is harder to replicate and hence less likely if you offer one seamless learning experience.

Your turn

Have you considered or tried to collaborate with training? Has it been worthwhile? Can this be a first practical step towards content strategy? Please leave a comment.

Top 3 success factors in online help systems

Service speed as well as content’s structure and spacing are the top 3 factors that determine whether your online help system is successful. That’s the gist when I apply 7 of Cameron Chapman’s “10 Usability Tips Based on Research Studies” to online documentation.

Cameron’s post of September 15 looks at the numbers behind the usability of web sites and, as she writes, “some might surprise you and change your outlook on your current design processes”. And they underscore the importance of offering documentation that’s quick to find, understand and apply.

Speed

Speed is essential for online help success in two ways.

Write help content so it is fast and easy to skim and understand. Cameron mentions two studies by Jakob Nielsen:

  1. Users read only about 28% of the text on a web site, and the ratio decreases with the amount of text.
  2. Users follow an F-shaped pattern when skimming web sites. They start reading at the top left corner (in cultures which read left to right, top to bottom), skim key words along the line and move down the lines in that pattern.

To optimize your online help for such behavior, you can:

  • Use headings, bullet lists and parallelism to ensure that users read the “right” 28% of the text. These are the parts which orient readers and guide them to the solution of their question, and then the solution itself (and hopefully they read more than 28% of that page…)
  • Front-load your headings, list entries and paragraphs so readers get the gist from the beginning.  This quickly guides your readers and helps them in their F-shaped survey of your contents.

Power your server so  it is fast to load and display the online help. Cameron refers to a study for the Bing search engine which shows significant decreases in clicks and user satisfaction once load times exceed two seconds. I assume that online help servers meet with similar impatience: Just like a search engine, they are intermediary services which users consult when they really want to do something else.

So measure and ensure that your online help web server can offer users short loading times. This is especially crucial in multi-step rendering processes of dynamic content which involve first a database and then on-the-fly rendering in HTML + CSS.

Space

The spatial design of information is the second essential factor in the success of your online help.

Use white space to improve readability and reading comprehension. A study at Wichita State University found that users prefer text on web pages with margins and optimal leading (= vertical spacing between text lines). They also retain better what they have read.

“Don’t worry about ‘the fold’”, says Cameron. Contrary to popular belief, users do scroll and read below the ‘fold’ of the initially visible top part of a web page. Cameron points to studies by a web analytics company and design agency which conclude that there is no correlation between page length and the number of readers who scroll at least 90% to the bottom. Instead, users apparently scroll when they think it’s worth scrolling – which again emphasizes the content, its readability and usability.

Structure

The structure of topics and contents in your online help is the third essential factor.

Navigation beats search. Cameron cites two studies that found users prefer navigation and usually resort to search only after the navigation failed them. (I assume this differs for experienced users who know what they can expect from navigation and search respectively.)

So do your technical communications team and your users a favor and maintain a solid topic structure that writers and readers find worthwhile to use. A good topic structure is a map that orients users throughout the system and in context. By contrast, a search result merely shines a spotlight on the topic a reader may or may not need. In short: Don’t let your search bail out poor structure and bad navigation.

Related topics

Improving documentation with web analytics, Rachel Potts at TCUK

Rachel Potts (@citipotts) held a 3-hour pre-conference workshop at TCUK, showing and instructing us how to use web analytics (such as Google analytics) to monitor and improve documentation. We went through three use cases, you can

  1. Answer specific questions, for example, how often was a certain page viewed. This is the simple, obvious use case where you just look at one or few numbers without having to do any data tringulation.
  2. Measure strategic process. This means to analyze available data top-down to find out whether documentation serves an intended purpose. For example, if exception handling pages in the online help have feasible numbers for page views and time on page, while customer support calls for the corresponding issues decrease, your strategy to offer self-service error recovery in online help probably succeeds.
  3. Measure content use. This means to analyze bottom up to find out what new insights can be teased out of the available. Take an online shop, for example. If you relate search terms with the products that were ultimately bought in the same visit, you can start to build a glossary of products which your customers relate to one another. This is not the well-known “Customers who bought that have also bought this…”. Instead, you might find that people looking for “loafers” often buy “sneakers”. Or people looking for “equity” in the online help often wind up at the “stocks” page sooner or later.

For the specific improvement of documentation, Rachel had prepared several exercises. The one I found most helpful had us develop an action to achieve a business goal with documentation content. This action consisted not only of a formula, a target and a frequency of what to measure in web analytics, but also of the underlying purpose and the underlying assumptions.

Rachel was very explicit on that last point: She warned us that we should always keep in mind our assumptions in our interpretations and in what we define as a successful outcome!

– I had never thought through how web analytics could be applied to documentation, so this was an insightful workshop for me. I believe that all three use cases can be applied successfully to complement user analysis and surveys. However, having documented web analytics software in a previous  job, I am skeptical about any absolute numbers to come out of the analysis. Instead, I trust them more to indicate relative change or progress.

Your turn

How have you used (or would you use) web analytics to monitor and improve documentation? Feel free to leave a comment.