What Is Information Architecture? A Guide for Technical Communicators

This guest blog post was written by Neil Perlin. Neil has 4 decades of experience in tech comm, with 35 years in training, consulting, and development for various online formats and tools including WinHelp, HTML Help, CE Help, JavaHelp, WebHelp, MadCap Flare, and more.

Information architecture has been with us for years. (I wrote an article in 2013 about re-architecting information, which suggests that the original concept of information architecture was established by then.) It’s also been around long enough to have become a sprawling topic whose full treatment goes far beyond one blog post.

For the purposes of this post and a subsequent one, I’m going to define information architecture in two different ways. One is by the audience, defining it as those features and methodologies aimed at authors versus those aimed toward user needs. The second is the generic definition versus MadCap Software’s perspective. I’ll also limit both discussions to what I consider to be the major features in each category. In this first of two related articles, I’ll focus on the author’s side. I’ll look at the user-side in the next post.

So what is information architecture? Think of it as a structure for creating content, with freedom within that structure. For example, if you build a house, you have the freedom to select light switches within the standards defined by the lighting industry. The difference is that the standards for light switches have been defined for you. You’re selecting the externals–the appearance–but are not setting or modifying the technical standards themselves. For technical communication, however, you’re actually defining the technical standards through items like templates and stylesheets. This adds complexity to the process but the authoring tool vendors have tried to simplify that process. You’ll still have questions when you start, you may still call tech support or bring in a consultant, but you’ll quickly move beyond the novice level.

With that, let’s jump in… 

Information Architecture for Authors

Time-to-market is getting shorter and supporting multiple outputs is getting increasingly complex. This means we can no longer “wing it” when it comes to organizing, structuring, and controlling our content strategy. (I’m focusing on text-based content models here, although other content models like video and augmented reality are coming into wider use.)

Templates – Generically

If you can define specific types of content that you’re creating, such as concept, task, reference, and so on (I’m not talking about DITA, although the idea of content types applies to both the DITA and non-DITA worlds), then you can create topic type templates for that content. The actual writing will of course vary depending on what’s being documented and will vary between different writers on the same project, but the templates turn authoring into a fill-in-the-blanks exercise that supports consistently structured content.

Templates – In MadCap Flare

Once you create templates in MadCap Flare, they’re easy to use and manage and almost impossible to overwrite. You create them as topics, add them to the Flare interface using the Manage Templates option on the Tools ribbon, and access them when creating a new topic by selecting them from your Custom Templates folder in the Add File dialog box. This is a huge information architecture feature.

CAUTION: I find that new Flare users refer to “the template” generically. Because every Flare feature is based on predefined templates, it’s important to refer specifically to “the stylesheet template” or “the master page template” in order to avoid confusion.

Stylesheets – Generically

Templates control content structure; stylesheets control the format of that content. (“Format” is usually taken to mean things like fonts, font size, color, etc., but can go far beyond that.) This way, if you define level 1 headings as Arial, 16 pt., blue, you can apply all of those properties at once rather than one at a time, without having to remember what shade of blue to use. This lets you quickly create consistently formatted content. And if you’re wondering whether templates and stylesheets can work together, the answer is yes. So adding content to a template field not only aids with content organization, but structures it, all automatically.

Stylesheets – In Flare

Flare has what I consider to be the most powerful stylesheet editor in this market. You might expect this much power to be equally complex but, in most projects, you can ignore most of the stylesheet features. If you have to focus your professional energies somewhere, focus on becoming fluent with stylesheets. 

Cross-Project Consistency – Generically

You may have to document multiple products. Each will of course be different but you want each piece of documentation to have the same information design to maintain a consistent company face to the world. We’ve dealt with this for years, usually by creating a stylesheet or templates and copying them to each new project. This works, but it’s easy to forget to copy a stylesheet or template to a particular project or to make a change in the stylesheet but forget to make that change in the copy of the stylesheet in project B. What we need is a way to install these “shared files” in each project and automatically update them across all the projects.

Cross-Project Consistency – In Flare

Flare offers a feature called Flare Project Import. This feature provides cross-project consistency. It lets you define one Flare project as a parent project and the other projects as child projects. You can then define the stylesheet, for example, in the parent project, then specify that the child projects should link to the parent and download and use the stylesheet from the parent. Any changes to the stylesheet in the parent are reflected in the child projects whenever you generate the output for one of those projects. There are many options but the basic concept is really this simple. 

I may have become a bore on the subject of the Flare Project Import feature over the years but I regard it as one of the best, and most unsung features in Flare.

Re-Usable Content – Generically

Within your content inventory, content often gets re-used within and between projects; think how often you might refer to a product by name and how difficult or annoying it can be to find and change every instance of the product name just before release. You could type the product name, copy it, and insert it whenever needed. If you need to change the name, just do a search and replace. Easy. But what if you typed the product name several times and misspelled it? The solution is simple, re-usable chunks of content. These have been with us for years, notably, in my experience, as “library items” in Dreamweaver.

Re-Usable Content – In Flare

Flare offers two forms of re-usable content models, variables, and snippets. Variables are text-only and usually used for short bits of content like product names. Snippets can contain anything that you would put in a topic, such as text, graphics, tables, etc., including variables. And variables and snippets can be used in the parent projects mentioned above to ensure wording consistency and, with snippets, content structure within and across projects.

Reviews – Generically

Theoretically, technical communicators collect information, turn it into content, then pass it to a subject matter expert (SME) for review. Many SMEs still write their comments in pencil, leaving it to the author to decipher the comments and make the changes in the content. In some cases, the SMEs use reviewing software to give their SME feedback. This is more efficient for the authors but a tough sell to SMEs who are asked to learn and use a new tool for a task that’s not part of their job description and that rarely benefits them. So one crucial factor for review software is simplicity. 

Reviews – In Flare

Over the years, MadCap Software has made several stabs at creating review control tools, first with X-Edit which became MadCap Contributor. MadCap Contributor was powerful–it offered almost the full Flare feature set–but too confusing for many SMEs. A few years ago, MadCap Software came out with MadCap Central and appears to have hit the target this time. MadCap Central offers a dramatically simplified set of features and workflow and is easy for SMEs to understand and use. 

Governance – Generically

You’ve probably heard the term “governance” but may not be sure what it means. Here’s a definition, from the Governance Institute of Australia at https://www.governanceinstitute.com.au/resources/what-is-governance/:

“Governance encompasses the system by which an organization is controlled and operates and the mechanisms by which it, and its people, are held to account. Ethics, risk management, compliance, and administration are all elements of governance.”

This is an enormously wide definition but we can pare it down for Flare authors and project managers.

“…the system by which an organization is controlled and operates” – This might refer to who must sign off on new content or changes to existing content, by when, in what order of precedence, etc.

“…the mechanisms by which it, and its people, are held to account” – This might refer to how the sign-off procedures are actually run, how proprietary information is treated, ownership of information and who can physically change it, etc.

We do all these tasks now, without software support, but it’s done manually, often on an ad hoc basis, and with no error-checking or enforcement. Which brings me to…

Governance – In Flare

Interestingly, MadCap Central strikes me as being as much a platform as it is a product, with MadCap Software being able to extend what features Central supports. 

Note that the next paragraph is my perspective on MadCap Software’s direction for MadCap Central, with no input from MadCap Software, so take it with a large grain of salt.

MadCap Central supports review features plus project control and management features like the ability to define what authors can access a project, what teams can work on a project, create tasks, reports, and more. And in keeping with the idea of MadCap Central as a platform that’s extensible, MadCap Software added support for analytics in 2020. While MadCap Central does not yet offer governance features, it appears likely that MadCap Software’s next step will be to add them by extending the features available to authors, teams, and reviewers. Once, or if and when, MadCap Software adds these features, the combination of MadCap Central and Flare will be able to compete against products costing hundreds of thousands of dollars. If your documentation needs consistency or has a complex review cycle, keep an eye on MadCap Central and Flare over the next few years.

Summary

It should be obvious from even this short post that MadCap Software offers significant support for information architecture. And Flare and MadCap Central contain many additional features that offer further support for information architecture even though they’re not information architecture features per se.

As I noted at the beginning of this post, there’s a second perspective on information architecture – the user level. Much of this is based on the author-level features defined here but there are others, mainly the implementation of search systems and search filters and responsive content design for material to be viewed on multiple devices. Watch for part 2 of this post in February or March of 2022 to learn more.