Help Center

How to structure your documentation’s information architecture (IA)

Michelle Chin

The information architecture (IA) of your documentation can seem daunting, especially if the design system is complex. Working with our customers showed us how unique companies, their teams, and their design systems are. Copying an IA from a similar company is difficult because we don’t understand why they chose that structure or why they need it. Although your IA will depend on several factors unique to your organization, we’ve compiled some best practices you can use. Let’s get started!

An effective documentation IA will enable people to efficiently and confidently find what they are looking for. IAs seem simple enough, but there are a number of factors that can influence how you structure them. These factors include: 

• The number of brands within the company – and your organization’s scope of impact
• The number and types of products in the product portfolio
• Which teams are involved in contributing, consuming, and maintaining the system(s)
• Short and long-term company goals around the product portfolio

The following activities will help you figure out some options for your documentation IA to make it work for your viewers and editors. Each exercise will be discussed in more detail later, but at a high level, they are:

1. Map the product portfolio 
2. Map the portfolio to a zeroheight structure
3. Identify friction points and apply some zeroheight magic for better IA
4. Mock up the IA in zeroheight and try usability testing
5. Iterate based on feedback

Activity 1: Map the product portfolio

This activity aims to map the current structure of your product portfolio and, if applicable, how it might evolve in the future (in 9-12 months). 

What you’ll need:

• Our Figjam template or a mapping tool of your choice, like Miro, Mural, etc. 

What you’ll do:

1. Map out your brands. This can be one brand, multiple sub-brands, or standalone brands. Note on the map whether these brands are closely aligned, should be aligned, or should remain distinct.
2. For each brand, map out if there are any product areas. Product areas can be considered smaller divisions within a brand or represent a suite or group of products. Note on the map if these product areas are aligned closely, aren’t aligned yet but should be, or should remain distinct. Some examples of product areas are:
   1. Internal apps and external apps
   2. E-comm sites, physical products, and digital apps
   3. Admin apps and end-user apps or employee apps and customer apps
   4. Work productivity apps and home productivity apps
3. For each product area, map out the products in each of them. Products are the actual applications (or physical products). For example, if you have an office suite product area, some applications are a spreadsheet app, a word processing app, and a slide presentation app. Note on the map if these products are aligned closely, aren’t aligned yet but should be, or should remain distinct.
4. For each of the products, map out the endpoints that exist. Endpoints are the devices where the products are. For example, the spreadsheet app might have web, iOS, and Android endpoints. Note on the map if these endpoints are aligned closely, aren’t aligned yet but should be, or should remain distinct.

Make additional notes on your map. Jot down things that could affect the scope of your or other teams, areas of future expansion or consolidation, or other factors that could affect the IA.

Activity 2: Map the portfolio to a zeroheight structure

In this activity, you will learn how to organize your product portfolio within the zeroheight hierarchy. Understanding the zeroheight hierarchy is essential before we start mapping.

zeroheight hierarchy

While zeroheight’s hierarchy is straightforward, it allows for a lot of flexibility, which can make things confusing. We also offer unique features that improve the site’s experience for viewers and editors!

Styleguides

Styleguides are the largest container that zeroheight provides. Larger organizations might want to create one styleguide for each large division (e.g., subsidiaries, product areas, business units). Separate styleguides are good if viewers focus on one area or don’t need to cross-reference things frequently.

Sections

Styleguides are organized into sections. Through the top navigation, viewers can access sections. This styleguide has four sections. Depending on an org’s situation, they might have one styleguide and create sections for each large division (subsidiaries, product areas, business units) or other large divisions (design system aspect, product, endpoint). Sections are suitable for dividing large areas in a styleguide.

Categories

A category is the largest grouping in a section. Categories are on the lefthand side and house individual pages. Categories themselves aren’t pages. They are suitable for chunking similar pages together (e.g., form components, app-specific components, or foundations)

Page

A page is a screen of content and is nested in categories. Pages make up the bulk of the content. Pages are suitable for specific elements or topics (e.g., buttons, inclusive language). 

In-Page Tabs

In-page tabs are optional and are a great way to add another level of hierarchy. They are sub-pages nested within the main page. The first tab is the default content shown when navigating to a page. In-page tabs help present different but related aspects of an element or topic, for example: 

• Design, code, content
• Web, iOS, Android
• Dark theme, light theme

Special features

To help make connections more seamless for your end users and editing simplified for your editors, zeroheight offers some unique features.

• Connecting styleguides – Sometimes, you might have complex systems or need brands/products more separated. However, you still want your viewers to access the information quickly. You can add links to your separate styleguides along the top navigation.
• Connecting content – The “synced pages” feature is a way to maintain one set of “base” pages and push it to other pages in your design system. Editors benefit because they’re only maintaining one set of pages. Viewers benefit because all the content they need is in one place.

Now that you have a base understanding of the zeroheight hierarchy let’s map out how it can work with your product map.

What you’ll need:

• If you haven’t used this in Activity 1, our decision tree Figjam template.
• Your portfolio map from Activity 1.

What you’ll do:

Follow the decision tree in our Figjam and answer the questions based on your portfolio map. This exercise will get you started and won’t necessarily be your final IA. We’ll fine-tune the IA in the later activities. As you work through your answers, start mapping the zeroheight hierarchy to your portfolio map. If you feel like this could get messy, feel free to work from a copy of your portfolio map. Also, consider where things are today and if they might change in 9-12 months so you can future-proof the IA.

Activity 3: Identify friction points and apply some zeroheight magic for better IA

This activity aims to remove any aspects of the IA that might hinder a viewer’s experience finding information. By the end of this activity, you should have a rough initial IA.

What you’ll need:

• Your portfolio map with zeroheight hierarchy applied (The work from Activity 2)

What you’ll do:

Make a copy of your IA and start making changes based on the following steps:

1. Look at your hierarchy and see if there are any confusing or bloated areas. Usually, when there are too many items under one group, people will have trouble finding things. 
2. Consider moving the potential pain points up a level in the hierarchy. For example, if there are six categories with fifteen pages each, consider making categories into sections and sections into separate styleguides. If you do this, you can provide viewers quick access to separate styleguides through links across the top navigation.
3. If there are too many items, consider reorganizing things into smaller groups. How you do this depends on the content and your viewer’s needs. It could be acceptable to have long lists of items if people are familiar with things already.
4. If there are areas of duplicate content, consider consolidating them, so there’s only one. For example, if the button usage is universal across all endpoints, have an overview page for usage guidelines. Then on each endpoint, identify anything unique to that endpoint. For design systems where there are or should be common components used, consider creating a “base” section or styleguide that everyone can reference. Then other sections/pages can contain content unique to those aspects. Another option is to leverage our synced pages feature. Identify which page should be the main and then create pages that pull in that information. 

Finally, you’ll have your initial IA, which we’ll test in the next activity.

Activity 4. Mock up the IA in zeroheight and try usability testing

In this activity, you’ll create a prototype of the IA, which you can test with your viewers and editors. By the end, you should know how well the IA resonated with them. 

What you’ll need:

• Your rough IA (The work from Activity 3)
• Your zeroheight account

What you’ll do:

1. Create a mock-up of your IA in zeroheight. The mock-up will serve as your prototype. Create styleguides, sections, categories, and pages based on your IA. You might have a lot of items in your IA, so at a bare minimum, create the styleguides, sections, and categories. Add some pages to the categories to give the prototype a realistic look. If you use in-page tabs for your hierarchy, include some on a few pages so participants can understand how they’ll use them. You don’t have to include design system content on the page since the IA is the main focus. We highly encourage you to mock this up in zeroheight since it’s swift to do so! 
2. Test the prototype with 6-8 participants. Testing might be an excellent opportunity to partner with user researchers to facilitate or mentor you through the process. If you’re relatively confident with the IA, consider doing some quick guerilla testing. If you feel the IA might be too complicated or this is a high-profile system, consider doing a more formal usability study. Participants should include a good mix of designers, developers, content writers, and anyone who would use the site. If you haven’t gotten editors’ feedback yet, consider having them participate. 
3. Make a note of where the IA did and didn’t do well. Just like any other usability test, there are lessons learned. We’ll use those findings in Activity 5.

Activity 5. Iterate based on feedback 

In this activity, reflect on your findings from the usability test. This might mean minor tweaks based on suggestions, reworking some areas, brainstorming with your team, or even consulting with a zeroheight Customer Success Manager or Design Advocate.

Depending on how much change you make to the IA, it might be worth testing again. 

Next Steps

If your team feels good about the IA, you’re ready to start populating your documentation site! 

Before you leave, here are a few things to keep in mind:

• Your IA should be long-term enough but also not set in stone.
• Design systems evolve, and company priorities change, so your IA will probably adjust, too.
• The right structure is the one that everyone will use!