Will structure and style make documentation processes less costly?

by Tom Johnson on Jan 26, 2014
categories: technical-writing

A reader writes,

Let me start by saying that I am a huge fan! I've been following your blog for many years and together with Mark Baker's and Scriptorium blogs, you've taught me 90% of everything I know about tech comm and documentation.

The problem at hand:

Documentation for our biggest product has grown enormous over the years. The growth was organic, as more and more features and complexity was added. Our online help for the product currently clocks at around 275K words. The project was first done in Word and then around 2008 we moved to Author-IT.

We've come to a point where the new content (both creation and localization) as well as maintenance of older content are very costly and management is pushing us to do something about it.

In a sense there are two problems:

1. Word count – I feel the writing style as it currently stands is very wordy. We don't have a specific style-guide and technical writers are left to their own devices.

2. Lack of structure – 80% of content is written in something close to free-form. Topics don't have any recognizable patterns. Similar sections are written in various ways across content. It gets to the point that I'm identifying topics which have 85% similarity but instead of reusing one twice two unique ones are authored, localized, maintained etc.

Additionally none of our writers are native English speakers, so it adds a level of complexity.

I am more than certain that our problems are not unique. I am also certain that a more structured approach in addition to controlled language (at least a style guide) can really have an impact on these issues.

Since you mentioned that you welcome questions, I've decided to reach out to you for some advice. If you have some statistics, maybe you've participated in similar projects or helped deal with similar issues (cutting documentation, cutting localization costs)? I would be grateful for all and any help here.

Thanks for writing to me. I'll add a few thoughts and then invite readers to add their own in the comments below.

It's important to get a better feel for just how much content we're talking about. 275K words at approximately 550 words per page means you have roughly 500 pages.

To begin, let's identify the problem. What exactly is the problem with the existing content? You say the creation and localization of new content as well as maintenance of old content is costly because there's so much of it. Management wants you to reduce the cost.

Why is it so costly to create and localize new content? Why is it costly to maintain old content? That's not entirely clear to me. Developing content is time-consuming, and so is maintaining it. Eliminating some of the content would make it easier to maintain -- unless that content is still needed by users. In that case, eliminating it would just increase support calls and user frustration.

Introducing structure

You mention that the content lacks structure and doesn't conform to a specific style guidelines. You hope those two measures will enable better re-use and reduce wordiness, hence making the content easier to maintain (which would drive down costs).

I am not sure you can draw the cause-and-effect relationships so easily. In general, moving towards structure and consistent style is a good move. The question to ask, though, is whether structure and style will reduce your costs? Maybe, but probably not in a significant way.

You're already using Author-it, which has solid capabilities for managing localized content. It also has good re-use capabilities. I don't think you need to move to structured authoring like DITA to take advantage of localization and re-use when you already have a tool that does a pretty good job at both of those things.

Additionally, if you require authors to follow a structured model, you're probably in for some training costs. I'm not sure how Author-it supports structured authoring. If you adopted a DITA structure, for example, you might have to modularize your content by separating out concepts from tasks in your source files. That may require a lot of rewriting. You would also have to train your authors, who might resist.

I gave a presentation at the STC Sacramento chapter last week where someone gave me some interesting feedback about DITA. I was speaking about information fragmentation, among other things. One of the attendees said he'd just had a call with 20+ writers in which they were encouraged to tone down the minimalism style they had adopted with DITA. They were rigidly separating tasks from concepts, or separating out subtasks from other tasks (I'm not entirely sure of the details). He said they'd received so many complaints from frustrated users about the fragmented information in the documentation that that they had to make some changes.

In short, while structured content probably has many wins over freeform content, it also has potential pitfalls as well if you don't implement your ditamaps with a goal-oriented architecture.

At the TCCamp unconference yesterday, Tracy Baker from F5 said there are a couple of main reasons to move to DITA. First, if you need a high degree of re-use, something much more than 5%, DITA's a good idea. For example, if you're re-using 40% of your content, such as sharing content between documentation and training for separate deliverables, DITA makes sense. The second factor is whether you're localizing your content. Before moving to structured content, ask whether you have these two requirements.

Migrating 500 pages of freeform content to DITA can be a significant undertaking, especially if you need multiple authors to modularize the content. Some people report that it takes them 2+ years to move to DITA. You can leverage conversion services, but if your content isn't already chunked properly, mainly with tasks separate from concepts, you'll have a lot of rewriting to do. I'm not saying that moving to DITA is a good or bad idea, only that the hoped-for reduction of costs might not be something you immediately realize.

Introducing a style guide

Re the style guide, if you have a lot of authors, you could adopt something like Acrolinx to enforce a style. This tool is a really cool style checker that you can customize with your own rules, but you'd have to sell your first-born child to afford it (I think the base price is $20k).

Second, even if you do want to introduce a style guide, you have the monumental task of getting your writers to adopt it (assuming you can find agreement in the first place). There are so many variations about comma placement alone that people will argue infinitely. At the end of the day, users don't care so much about the details of style as long as the content is accurate.

If your style can reduce wordiness, though, that's probably a good strategy. For example, if writers are tacking on needless result statements after every step, those can often be eliminated.

I'm surprised that you don't already have some kind of style guide in place. You could just introduce some style best practices to reduce wordiness. You don't need to flesh out a 100 page style guide full of all kinds of gory details. Just go for a dozen style guidelines that likely address the wordiness problem.

If you adopt an existing style guide such as the Microsoft Manual of Style, highlight the sections you want people to actually read and follow. Otherwise no one reads it.

Innovating with documentation processes

Beyond moving to structured authoring or introducing a style guide, are there other things you can do to reduce costs and make it easier to update and maintain content?

There might be some efficiencies you can introduce with your processes. Let's leave the decision about structure and style alone for now. What really takes so much time in developing content?

One question to consider is when technical writers get involved with a project. Is it more efficient to get involved earlier or later in a project? If you get involved earlier, you have more time to learn the features that you need to document. But most likely those features will change several times, requiring you to rewrite your content each time.

It might be more efficient to join projects later in the software development lifecycle. Jump in when the features you need to document are 90% frozen and practically hitting Quality Assurance teams for testing. Granted, this leaves you little room to suggest interface changes or do anything else but focus on the product, but you can rest assured things won't change. You won't have to rewrite documentation due to changed interfaces and functionality.

A second efficiency would be to leverage the testing scripts that Quality Assurance teams use. What tests are QA engineers running to ensure the software is functioning correctly? Sometimes leveraging those test scripts can give you a jump start on the documentation.

Third, you might choose to triage your efforts by focusing on the 20% of the scenarios and tasks that result in 80% of the product's usage. Perhaps you're focusing too much on edge cases or nonstandard scenarios. You might take a more knowledge-management-centric approach to document creation. In this model, you do the bulk of your writing post-release based on the questions and issues that users have (rather than pre-guessing what questions and issues users will likely have).

Fourth, consider where you physically sit in your company. Are you located near the Engineering teams that create the code you need to document? If you're isolated from the engineers, you may not be getting the right information at the right times. Moving your doc teams closer to the engineers or other experts, such as product managers, may open the flow of communication, allowing you to get the information you need.

Fifth, consider ways to speed up the review process. If you have a lot of people creating content, especially subject matter experts, are they following a process they find tedious and loathsome? For example, are you asking subject matter experts to create content using a tool they dislike, and asking them to undergo a review process they find inconvenient (like marking up a PDF)? In my experience, Google Docs is a great platform for developing content. It's easy to create and review content. You can comment in the margins, allow multiple simultaneous reviews, see revision histories, share it with as many people as you want, and more.

Once the content in Google Docs is finalized and you're ready to publish it, you can move it into your publishing tool. In Google Docs, I use a lightweight markup called Markdown so that I can convert the content to HTML via http://stackedit.io in one click, and then paste it into my publishing tool.

Sixth, another question to consider is whether you have enough training and knowledge in your specific industry. Are you faced with a complex subject matter that strains you every time you have to document something? If so, you might leverage online technical resources (such as safaribooksonline.com) to ramp up on some of the technologies that you're documenting. Augmenting your industry expertise will make you a more efficient writer.

Seventh, consider specializing your team roles. If you have multiple writers who must each define the style sheets and outputs for their products, you can develop more efficiency by specializing the documentation roles. Designate one person to be the tools expert. This person sets up the publishing process so that others can focus on content creation. You can also specialize your team members by designing one person to focus on a specific product and have other writers to focus on other products. Through this specialization, each writer can develop more expertise and efficiency.

Overall, if you're eager to introduce structure and style guidelines, go for it. But also keep yourself open to innovative processes that will make you more efficient.