Communication

How to bring modular architecture to your design documentation

by

on

View all posts

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:

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?

A graphic representation of the modular architecture hierarchy.

A graphic representation of the modular architecture hierarchy.

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.

doc-2

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:

A partially complete master document.

A partially complete master document.

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.

Master folder containing 4 topic folders, and a master document.

Master folder containing 4 topic folders, and a 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:

A completed master document.

A completed master document.

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:

doc-6

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.

More posts like this
CTA for those not in hs to DO UI kit
Author

Yona Gidalevitz
Yona is Codal’s technical researcher. At Codal, he is responsible for content strategy, documentation, blogging, and editing. He works closely with Codal’s UX, development, marketing, and administrative teams to produce all manner of written content. You can check out his work on Codal’s blog, Medgadget’s blog, and Usability Geek. In his free time, Yona is an avid guitarist, cook, and traveler.

Join over 2 million designers

Who get our content first.

No sales pitches, no games, and one-click unsubscribe.

Over 2 million designers
get our newsletter
every week

Find out why

Get awesome design content in your inbox every week

Just like over 2 million of your fellow designers do.

Plus get 3 free downloads, just for signing up.

Give it a try—it only takes a click to unsubscribe.

Thanks for signing up!

You should have a thank you gift in your inbox now—and you'll hear from us again soon!

Prototype better experiences with InVision

Just like over 2 million of your fellow designers do.

I agree to InVision's Terms of Service.

Want a free t-shirt?

Join the 2 million+ designers who get our newsletter weekly for your chance to win!

We hate spam as much as you do, and you can unsubscribe anytime.

Double your chances to win!

Tweet and automatically get a second entry

Tweet Now

No Thanks

Stay in touch!

We share news, freebies, and more on Twitter.