top of page
  • 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 different, mark it up as such. The key is to find a balance between significant gains in content reuse and a structure that is maintainable.

Finally, make sure others can understand your solution and confirm it fits what was workshopped. Establish when the context or audience creates the need to deviate from the planned structure of content. You’re creating this content reuse strategy to maintain consistency and quality, and that analysis and planning is critical, but once done, it needs to be like an agile roadmap that allows flexibility to adapt to reality once the actual writing begins.

Your analysis from the initial document structure reviews and deeper dives in topics, sections, writing styles and approaches should allow you and your team to identify patterns and trends that serve as the foundation for the information architecture. You will establish a consistent and comprehensive framework around how to implement a content strategy that truly fits your needs.

The Content Model and Writing Guidelines

If you’re working in a structured authoring (XML-based) solution, your toolset will help maintain consistency by enforcing rules for the content structure. To a great extent this will be done automatically by the structured authoring tool, through validation. So choosing to work with a rich semantic XML content model in itself enables good information architecture. But it doesn’t quite mean it’s all automatic. The information architect still needs to make decisions on which elements to use, as well as how and where to use them. The content model may provide the right semantic elements for procedures, admonitions (notes, warnings, etc), examples, figures, and so on. But there are many choices to be made. Should you use “guilabel” elements to mark up content about a software applications components? Should you be even more exact, using “guimenu,” “guibutton,” and other granular markup? All this needs to be decided, and it should be documented in a structured writing guide.

Structured authoring will do part of the work for you, but to use it correctly and consistently you should set up some well-documented rules and guidelines.

Categorizing Content

Another important factor of good information architecture is categorization of content. Categorization is something that is natural to all humans, and we do it all the time, even without realizing it. It’s at the core of how we understand things and concepts.

Naturally, categorization plays an important part of technical documentation as a whole. Just consider a table of contents, that’s a categorization of topics right there. But it’s not just about organizing the content. When it comes to structured authoring and content reuse, you’ll also need to establish the right categorization on multiple levels.

For instance, if you are going to create related topic links (sometimes called “See Also links”, you need to categorize to find the relationships. In Paligo this would result in a taxonomy to use for creating the related topic links, which could also mean organizing the categories in hierarchical trees (depending on how far you want to go).

And when you get to conditional filter attributes and variables, you’ll need to decide on which dimensions to vary your content. Which filter attributes should you use for example (market, product, country, user level, etc)? And within those filters, what values make sense with regard to how the content can be categorized?

But here’s the rub: humans all categorize to understand and organize concepts, but we don’t always categorize the same way. (As an interesting case in point, check out the book “Women, Fire and Dangerous Things: What Categories Reveal About the Mind” by George Lakoff. The title comes from the rather amusing fact that in Dyirbal, a native Australian language, “women, fire, and dangerous things” represent a cluster of related objects in the experience of that culture.)

So while you may think you have a clear picture of the subject matter you are covering in your technical documentation, can you be sure that your categorization of the content is shared by others? Probably not entirely. You may have many technical writers on your team, all with slightly diverging views. You’ll have the end users, the final consumers of the documentation. You need to know who they are, and try to work out if their classification of content will coincide with yours. So how do you go about this? If you are documenting a really complex subject matter, you may need to use workshops, surveys, and other tools to work out the classification model. But in many cases it doesn’t have to be as complicated as it may sound, just thinking through all these aspects and doing the analysis will be enough.

When you take a closer look at your representative content, you identify categories and strategies for designing smarter content that meets your audience needs, reduces errors, and improves user experience. A proper information architecture analysis helps you get started utilizing the tools available to create structured authoring successfully.

Good luck with your information architecture.



bottom of page