Examining the load-bearing walls of product information architecture

Content Audit and Style Guide Revision

Comedian Bill Bailey has a joke about the Hindu Trimurti, the trio of gods Brahma (the Creator), Vishnu (the Maintainer), and Shiv (the Destroyer), mocking the dubious glory of occupying the role “Maintainer.” Compared to the exciting prospects of creating or destroying, who wants to be responsible for merely maintaining? 

But as far as help content goes, maintenance is where it’s at.  You want consistency, standardization, and a coherent voice when communicating via the help files containing most of the information about how to use a product– especially when that isn’t on the screen in the app itself, staring the user in the face already– and sometimes even when it is.

What’s the problem?

A site hosting documentation for a library of products and services across a platform, where users can find help files and user guides, needs to be audited occasionally for various reasons, including:

  • The frequency of updates to each product or service may vary significantly, and corresponding updates to the documentation for those goods and services might fall behind.
  • New products are introduced semi-regularly, necessitating creation of their own documentation.
  • Content design team members and their product assignments shift over time
  • Style standards and best practices also change over time, and revisiting them as a team allows everyone to contribute and make decisions going forward. 

But somebody needs to perform that audit, and even apart from it being wildly impractical to expect the entire team to do it, there’s a benefit in having a single person combing through the files, actively comparing/recording differences between them. 

Why bother?

Help content should be accessible– easy to understand, easy to find, and easy to consume. It also needs to be accurate, current, and relevant. 

In all of these aims, consistency is vital. One disenchanting experience while trying to figure out how the product works can frustrate a client and diminish their trust in the help files, the product, and even the company.  Inconsistency in voice and tone is confusing, and inhibits presentation of the company’s offerings as a coherent whole. 

Internally, team members need to be in accord on what they’re trying to communicate, and why, and how. Figure that out, then update the CSS. 

What’s the goal here, anyway?

  • Identify areas of inconsistency between the help files for one product and another.
  • Discuss those inconsistencies as a team.
  • Find areas where the content should be updated across the site.
  • Each writer gets to work on their own set of puzzle pieces, sanding off edges and rounding corners until they fit together as a whole. 

What did you do?

Step 1: My job was to audit help content across the documentation site, performing a quality control evaluation to check for how (or if) features of help content are represented in the files for respective products.  My inventory ended up documenting over 30 features in the help files where I saw variability between products. These fit roughly into the following categories:

  • Landing page layout, including the content of cards/tiles comprising the main body of the landing page
  • Downloadable content on the product’s site, such as PDFs of user guides
  • Naming conventions for the collection of files (e.g. guides, help) and their introductory content (e.g. background, overview, introduction)
  • Formatting of ordered and unordered lists, tables, and callouts
  • Standards for, and formatting of, items in a procedure
  • Content in the navigation
  • Treatment of screenshots and other graphics
  • Video content
  • Internal and help/support links

Step 2 (The Team): In a series of team meetings, collaboratively do the following:

  1. Review the data from the content audit listing usage of e.g. breadcrumbs, dropdowns, special paragraphs such as notes and cautions, ordered and unordered lists, and standards for writing procedures.
  2. Research usage of these elements, styles, and standards as represented in help documentation for other branded products
  3. Discuss, as a group, how to apply these learnings to our own documentation.
    • Where there are differences– should we emulate those other brands, or are there good reasons to keep doing what we’re doing?
    • Are there any areas where we don’t really have a standard, and we need to create one to follow?
    • How big of a priority do we need to place on applying the changes we’ve agreed to make?  What updates can be made in the stylesheet vs. need to be performed by individual writers?
  4. Decide, allocate, and implement as necessary.

What happened next?

We not only reached a clear consensus on which standards found in some products should be applied universally, but also re-designed elements of the navigation, callouts, and landing page layouts. Everybody had a clear idea, going forward, of what style, word choice, and formatting standards to follow, as well as why those choices were made, because they were part of that decision-making process. 

It’s easy to become siloed when you’re part of a tech writer team while also integrated into a product team as part of their scrum process. Getting everybody together to talk about their respective views on content consistency also meant swapping information about the products themselves, and the product teams by extension. As a result, there were multiple beneficiaries in the process– the customer base consuming help content, the product teams themselves, and the writer team creating content that connects all three.