Embracing change

In the time since this article was published, I changed jobs twice within IBM and now work elsewhere. I still apply lessons I learned during the 7+ years I spent growing with the development team I worked with when I wrote this article.

First published in Intercom in Volume 59, Issue 1 (January 2012) by the Society for Technical Communication.

It’s very rare for a project to end up exactly the way they it was planned. There are many internal and external sources of change that significantly impact the design of your documentation: design changes in your products or services, customer feedback, competitor or industry changes, shifts in available team resources, new government regulations or industry standards, trends in documentation source and delivery formats, and so on.

If you work in the software industry and follow an agile development model, you're working in an environment that is inherently open to change and requires the flexibility to quickly adapt. It’s clear that we can’t simply avoid change, but you can work to minimize it - and do so in a positive way.

As the information architect (IA) at IBM for a development team that has experienced a lot of change, I can attest to this. Since 2003, the main product I work on has undergone several complete user interface and technology platform overhauls and has been combined with different product portfolios every few years to align with various sales and marketing strategies. Our team has become more geographically distributed over the years, and we recently moved to an agile development model.

Through all of this, I've had the pleasure of working with a documentation team that has learned to embrace change. I'd like to share some of the strategies we've learned, and while these experiences are in the area of software development, the approaches are applicable to documentation teams in other industries.

One of the main reasons I enjoy working in the field of technical communication is because I enjoy teaching and helping others. By sharing the experiences of our team with the STC community I hope to motivate others to embrace change and continue discussion of how we can use it as an agent for designing better documentation.

Change is an opportunity!

Embracing change is more than just a set of procedures or approaches – you need to believe in working with change instead of against it and that belief needs to be a part of your team’s culture.

The trap that many teams fall into is taking a victim or martyr position. Deviation from plans is “bad”. Even if the team expects that change will happen, they don’t plan for it. They take a tactical approach to change and simply react when a change happens instead of designing documentation that is flexible enough to adapt. A team with a “victim” response to change either does the minimum work required to meet requirements or outright refuses to deal with the change—even if this means compromising the user experience. A “martyr” team scrambles to deal with the change by accepting to do everything they were asked to do—with many extra hours of effort and often compromised quality.

A team that can successfully deal with change

• Believes that change is an opportunity to revisit the documentation and improve it.
• Takes a strategic approach to change by:
  • designing documentation that can more easily adapt to new requirements
  • evaluating requests for change to understand the real need before responding

So how do you get your team to see change as an opportunity? When a change occurs, work with your team to explore options and ways to positively respond. Some of the following questions might help:

-Can we find another team that has successfully dealt with this change so that we can reuse their solution?

-Do we have to implement the change the way we are being asked to? Is there better way or simpler way to resolve the problem?

-What part of the requirement actually matters? If you are being asked to change five things, but only two of them really matter to your customer, maybe you don’t need to do all five things or maybe you can do some of it later.

-What is the actual need behind the change request? This is a particularly important question for design changes that come from customers or customer advocates. Sometimes the solution that a customer says that they want isn’t the best way to give them what they actually need.

With the right attitude about change, you feel less trapped when something unexpected happens. By exploring your options, you can sometimes save yourself some work or even avoid making major changes to your existing documentation. And the lessons that you learn during the exploration feed into incrementally improving your documentation design.

Change-friendly information architecture

A key part of handling change more effectively is designing documentation that you can more easily modify or adapt. Some positive strategies to accommodate change are:

1. Design for reuse
2. Focus on your customers
3. Reduce your overhead
4. Develop partnerships
5. Foster a culture of knowledge sharing

1. Design for reuse

Designing for reuse means maximizing opportunities to write content once and reuse it across your library. Reuse can be as small as a single term or as large as an entire document that is reused in multiple libraries.

Beyond making your documentation easier to maintain if you need to change some content, documentation designed for reuse is easier to restructure with minimal rewriting, combine with other documentation created by other teams, or filter for different output formats or different editions of a product. It can also provide significant savings for translation because translators do not need to retranslate the common text that is reused across a product library.

Write for reuse

Reusable design includes more than just single-sourcing—where the options can be limited by the authoring tool you are using. Just adjusting the way that you write can make a significant difference.

For example, to make documentation more reusable, write in generic terms when it does not impede clarity.

Topic-based writing and single-sourcing

The DITA Open Toolkit documentation describes a topic as “a unit of information with a title and content, short enough to be specific to a single subject. A topic should be short enough to be easily readable, but long enough to make sense on its own.”

If you write your information in small pieces that are relatively-self contained, but can be organized into user contexts, then it’s easier to add/remove/move and reuse individual topics. For example, if your company has a product line for cataloging, you might have specific products for cataloging music, home inventory, and books. There will be some use cases that will be the same such as “Creating a new collection” or “Defining a custom category” and other use cases that will be unique to a product such as “Adding album cover artwork”. By writing individual topics for each use case as self-contained units, you can create multiple sets of information with common content.

Topic-based writing isn’t the best approach for some types of documentation. For example, in Developing User Assistance for Mobile Apps, Joe Welinske argues that on mobile phones, the small screen size and differences in user interaction from a desktop computer dictates an approach to documentation that is requires minimal reading and navigation. But in many contexts, a topic-based approach can significantly simplify reuse.

Beyond topic-based writing, you can look at other single-sourcing strategies. The subject of single-sourcing has been covered extensively in the past so I won’t go into details here. Essentially, the options will depend on what tools you are using. For example, DITA is inherently designed for topic-based writing as well as defining variables (content references), organizing topics into reusable groups with maps, allows filtering and flagging of content, and provides support to output to many different formats. A tool such as FrameMaker with a long history of traditional book-based design, might not lend itself as easily to topic-level reuse, but it does provide the ability to group files into different collections for reuse, define variables, filter content, and output to multiple formats and there are third-party tools that can help you to break down and organize the output in different ways.

Leverage your source control or CMS

Some source control and content management systems enable you to store your source in reusable pieces so that you can selectively check out pieces and combine them to create the output that you need. For example, Rational Team Concert enables you to group projects into components, and components into streams. You can then create build automation that checks out individual components from different streams to create custom sets of documentation.

2. Focus on your customers

Document what’s important

Why document everything if you don’t have to?

Customers don’t want to read the documentation unless they have to. And when they get there, they don’t want to spend a lot of time reading. But customers also expect to find enough information to get the job done when they get to the documentation.

When you hear these messages from customers, it might appear at first that there are two conflicting messages:

• “We don’t want to read. Make the docs as short as possible”
• “We want everything to be documented so that we know what to do if we need to read the docs”.

It isn’t that simple, however. When you ask more questions about the real source of the problem, you’ll discover what you really need to address. For example:

• The user interface was difficult to understand, so documentation had to be written to explain how to use it in detail, and frustrated customers are forced to wade through the information.
• The information customers need is scattered throughout the documentation so it is hard to find everything or it takes too long to find it all.

Once you know the real source of the problem, you can work to address it. For the previously mentioned examples, you can:

• Help customers before they get to the documentation library.
  • Work with Development to improve the user interface text and error messages. Well-designed interfaces require less documentation--which ultimately means that the product is easier for customers to use and the documentation is easier to maintain.
  • Implement progressive disclosure and put more information in the UI and error messages.
• Focus on improving the documentation for areas that are the most complex or that cause the most user confusion based on support and customer feedback
• Provide overview roadmaps and troubleshooting diagnosis roadmaps. The roadmaps provide quick reference information for the overall user scenario and provide and pointers to more detail. Figure 1 shows the HTML version of a roadmap in tabbed view. The PDF version is linear only and does not include the tabs.

Figure 1. Roadmap in tabbed view.

In essence, the “Document what’s important” principle is the 80-20 rule. If you focus your limited resources on providing usable documentation in the areas that are most important to your customers, your customers will thank you for making their jobs easier. In some situations, our team has delivered documentation with little or no information to describe some features. But because we focused on delivering usable information instead of documentation completeness, we received positive feedback for covering the areas customers cared about and very little feedback about information missing in areas we didn’t focus on. In fact, some of those sparsely documented features were dropped after a while anyway.

Organize based on user scenarios

Design your library around user scenarios. The major use cases for your product are more likely to be stable over time than the way features are grouped and organized. As mentioned in the introduction to this article, our flagship product has had several major interface overhauls, but because we’ve focused on organizing the documentation around the major use cases instead of how the interface is organized, it has been easier to accommodate additions and deletions of specific features or use cases in many situations.

3. Reduce your overhead

Look for ways to automate

By automating some parts of documentation development, your team has more time to focus on design and writing.

• Generate docs from code when there is reusable content in the code (e.g. database schema, API reference)
• If your tooling has a command-line interface to create output, create scripts to generate your output and publish it on a server so that it’s available on a scheduled basis for others to test or review.

Improve processes and standards

Document your processes to ensure consistency and help onboard new team members

Keep your processes simple. If they are simple, people are more likely to follow them. And the processes are easier to adapt/change.

Establish some conventions that will help your team to work more effectively. For example, using consistent file naming conventions for related information can be a step towards automation or restructuring and reusing information in the future.

Work in an agile or iterative way

Can you do ongoing informal reviews instead of formal reviews of frozen content? This means that writers deal with smaller sets of changes, and changes are more relevant to the current state of the project. This is particularly true in an agile development model where a comment that applied to the documentation two months ago may no longer be relevant.

Even if you aren’t working in an agile model, focus and commit to the highest priority work first – again with a focus on the customer.

4. Partner with other teams

Sometimes going outside of the writing team can give you a different perspective.

• Can your IT or development team think of ways to automate some of your documentation development?
• Ask your support or test team for ideas on how they would change the organization or design of information that needs to be changed or that customers find difficult to use. Show them prototypes for ideas that your team has for redesign. Customer advocates within your company are particularly valuable if you don’t have direct access to your customers for feedback or if you need input on information that you can’t expose externally yet.
• Can people outside your writing team help you to supplement the documentation? For example, our team has a wiki where anyone in our organization can contribute information about using the product.
• Can people outside your writing team help you to write the documentation? If so, write some guidelines and provide examples so that you don’t need to do as much editing when they complete a draft.

5. Foster a culture of knowledge sharing

Encourage sharing within your team and across your organization. If you share a great idea with another team, there’s a good chance that they’ll be there to help you with a solution when you need help. As you build a network of contacts, you’ll be able to work together on common challenges and reduce the load for everyone.

By sharing your team’s ideas you can help to drive standards. When our team joined a set of products that shared a common technology platform, we needed to work together to define standards for reuse that spanned all the teams. The documentation team for the platform was new to IBM. Many of the product teams in the group had no experience with DITA and little or no experience combining documentation sets. By sharing our team’s best practices, not only did I help the entire group to more quickly adopt a common set of standards, it also meant that our team didn’t have to make huge adjustments to our existing information architecture.