How to bring modular architecture to your design documentation

I’m Codal’s resident technical writer. Because I work among a group of UX specialists, I often take note of practices that are common in other fields, yet are criminally underused in UX.

Here’s one for you: modular documentation.

Modular documentation was designed to streamline workflow, help with organization, and promote reusability. But its key benefit is that project stakeholders can access any piece of documentation at any moment—without derailing you from your work.

“Modular documentation is criminally underused in UX.”

No more sending documents, attaching files, or uploading documentation to project management systems. Simply notify the stakeholders that the modular document has been updated, and leave the rest up to them.

What in the world is modular documentation?

Modular documentation is exactly what it sounds like. You create a central “hub” document that follows a modular architecture, linking out to strategically grouped “microdocuments.” The document groups are called “topics” and they’re centralized within topic folders.

Consider this modular documentation glossary:

It may seem like these definitions are generalized and irrelevant to the UX industry. That’s because you’re right. This is an adaptable system—it works in technical writing, it works in UX, and it works in administrative environments.

As a system, modular documentation can bring value to nearly any industry where documentation is frequently created and used. In the context of UX, modular documentation holds the key to unprecedented organization and communication.

Why should you care? For starters, your stakeholders will love it. They’ll be able to view any piece of documentation with ease—and with proper context.

Other teams, such as the development and visual design teams, will be able to easily locate any and all assets. Just give them access to the master document.

If you work for a company with a huge design team, assets like logos, colors, and style guides may often be reused from project to project. Modular documentation was originally designed specifically for reusability.

So, what does a modular framework look like?

You may be thinking, But how do I implement this new way of documenting things? Here’s how:

Create your master file and topic folders

It all starts with the master folder. Simply create a folder and name it after the project it’s intended to serve. Ideally you’d name the folder “Project Name.” For example, if this were created for Showroom Squared, one of our clients here at Codal, you’d call it “Showroom Squared.”

We use Google Drive for our file organization—it saves time when sharing documentation, and it’s secure. You can use whatever you like—Google Drive, Microsoft OneDrive, a plain old folder on your desktop. At the end of the day, it doesn’t matter.

Create the master document. This can be a Google Document or a Word File, depending on your chosen file organization system. Name it “ProjectName Master.” So, in keeping with the above example, we’d name this document “Showroom Master.”

Next, provide a brief description of the project and scaffold out your link structure by determining your topics. Don’t worry about listing every possible topic at first—you can add or change topics as you develop your documentation. That’s the beauty of modularity.

The topics in your master document will correspond (and subsequently link) to topic folders. Be sure to leave room below your topics for a section with microdocument links. At this point, your master document should look like this:

Now, create your topic folders within the master folder. In keeping with the above example, we’d create 4 topic folders: “Discovery & Planning,” “Research & Strategy,” “Conceptual Design,” and “Detailed Design.” Link these folders within the master document.

The topic folders you’ve just created will contain all manner of microdocuments: from sprint plans, to surveys, to user tests, to sitemaps, to interactive prototypes—anything relevant to the project.

Put absolutely everything into a microdocument

Quick refresher: A microdocument is a specific, focused piece of documentation.

In the realm of UX, this means everything you create for the project, up to and including the actual designs, will become its own microdocument.

As you go about creating these microdocuments, make sure to do 3 things:

1. Give them descriptive names
2. Add the microdocument to the appropriate topic folder
3. Create a link to the microdocument at the bottom of the master document (create a section for this in the same style as you did for the topic links)

Eventually, your completed master document should look like this:

Your master document is a living, breathing document. The list of topics and microdocuments will grow and shrink as the project progresses.

Anyone with access to the master document will be able to find a specific microdocument, or view all microdocuments within a particular topic, depending on their needs.

Conclusion: Modularize your UX documentation

Ready to modularize your UX documentation? It all starts with the chart. If you want to create modular documentation for sales content, for example, you’d create a chart like this:

Structure your documentation in a way that makes sense to you (and to everyone involved). The rest is simply a matter of following the advice presented within this guide.