• Marianne Calilhanna

Information Architecture 101 for Technical Writers

Guest blog post by Anders Svensson, CEO of Paligo

Whether you are a lone technical writer in a small business, or one of many in a large enterprise, at one point or another you’ll need to consider the information architecture of your technical documentation. Because your content has variations—variations that grow and multiply as time goes on. Over years of having more than one writer’s voice, multiple but similar products, and an accumulation of content from user manuals to product catalogs to online help and knowledge bases, you end up saying different things about the same topic using different structures, and content can get updated in one place but not another.

Getting team members to come together to decide on elements, structures, styles, and best practices for content reuse is critical to creating a unified message and managing the collections of content.

So what is information architecture anyway? Let’s start with a definition. Information architecture at a high level is a focus on organizing, structuring, and labeling content in an effective and sustainable way. But of course, that can mean so many things, and information architecture is used in all kinds of domains. Here we’re going to look at it specifically from the point of view of technical documentation, and particularly in a structured authoring environment. This includes a number of key activities that we are going to delve into:

  1. Gather stakeholders for workshops

  2. Content inventory – find a common structure

  3. Content audit – decide on and aligning your content reuse strategies

  4. Establishing a consistent content model and guidelines

  5. Categorize your content

Information architecture is important because it helps the users of a structured authoring system clearly understand and use it efficiently, as well as create content that is uniformly aligned, well-organized, and with powerful and maintainable reuse. And this in turn helps create quality content that end users can find, consume, and use. Nowadays, with content moving beyond just paper-based and into multiple systems/formats, organizations can deliver better content using a structured authoring approach. Rather than everyone just writing in silos, creating different styles, different content, and different structures using various software products, you establish a process upfront that guides the structure and approach to writing, editing, publishing, and retiring content. And you can customize what users see and when with “smart content” that is responsive to user preferences and needs, such as language or device.

Gather your stakeholders

With a firm grasp on the definition and purpose for creating an information architecture, you can begin an assessment process. One of the best ways is to set up a series of information architecture workshops. Including people from the outset in the analysis is often helpful. It gets writers and stakeholders involved in developing the set of rules, structures, categories, and techniques. If the budget is low and it is not feasible to have everybody directly involved, a survey can do the trick too, and gives you good input for the process.

If you see the value in workshops to evaluate and improve content, yet don’t believe your department or company will give you the time or resources, spend some time working through the business case for leadership. There are massive business benefits not often realized by management in terms of reducing errors, improving user experience, and getting products to market quicker.

The Content Inventory – Finding a Common Structure

The first step in the information architecture process should be to figure out what content you have now, and how it is structured. You’ll be surprised to see how little you actually know about your existing content when you start analyzing it.

The key task here is to find the common “master structures” of your documentation set. This will be like a macro level table of contents. The idea is that you need to find out if you have content with similar subject matter, but different structures. If so, you want to align that content into a common macro structure. This sets the foundation for the other tasks. Without it, it will be very difficult to analyze content on a more granular level.

Analyzing all your content may seem like an overwhelming task, though, but you don’t have to do it all. Start with a small proof-of-concept. Pick a few publications that are overall representative of all the content variants you need to categorize. Minimizing the number of samples reduces the initial time commitment for team members to analyze and strategize the organization’s content.

Example: Your company manufactures heavy machinery products, and has over 100 products that various writers have documented and organized in product families/series. To start the analysis, review an example or two from each product family so you don’t miss critical categories. The task is to find the common macro structure here, and an example of how a common structure could look for heavy machinery might be something like this:

  • Introduction

  • Safety

  • Transportation and Storage

  • Product Description

  • Commissioning

  • Installation

  • Operation

  • Maintenance

  • Technical Data

  • Troubleshooting

Start with a spreadsheet, organizing the content from different sample publications into the categories. It won’t always fit, and that is a finding in itself, but more importantly: you’ll often see a lot of inconsistency that is completely arbitrary.

Any team can conduct at least 1 to 2 workshops, and to start getting value from the process; just remember that you don’t even have to evaluate all content for the effort to provide value.

The Content Audit – Finding and Aligning Content Reuse

Now that you have organized your content into common structures, the next step is to do a Content Audit for reusability. You’d now start filling up another spreadsheet matrix with the common structure at the far left, and then add columns with topics at lower levels. If we take the same example as above, where we are looking at a number of similar products, you’d finally add columns to the right with the different products. (The dimension doesn’t have to be different products, though, it could just as well be many different deliverables for one product. The process is the same).

At this stage you need to look at the content in a more granular way to compare it. For each topic, mark up in the matrix topics that are really covering the same subject matter. You’ll find some are arbitrarily different, and so can be considered reusable. One way of marking this up is using a letter system: start marking with the letter “A”, and then mark any other topics that can be completely reused with the same letter. If a topic in the same category cannot be reused at all, continue to the next letter, “B”, and so on. But then, complement the letter system with a number system representing ways of making content more reusable (such as filters, variables, etc). For instance, if two topics are nearly identical, and using filtering on them could make them reusable, use a number to indicate the reuse technique. If we say that “1” represents filtering, you would then mark a number of topics that can be reused if filtered with “A1”. Here’s an example of such a system:

  1. Reuse topic if filtered

  2. Reuse with variables

  3. Reuse if split into separate topics or fragments

  4. Same content, but need to align writing

  5. Reuse with structure (entire sections, such as “chapters” or the like)

The review and categorization process doesn’t have to be perfect! You can (and should) incorporate more samples and continue to refine categories when your team starts the actual restructuring and rewriting of content.

This analysis of representative items uncovers patterns that you didn’t realize were there before, as well as divergences that exist but shouldn’t (saying the same things in different ways in different places, when they could/should be identical).

It’s also important not to overdo the hunt for reuse here, though. If content is too differ