UI/UX DESIGNER & RESEARCHER
HarvardSites Design System Ops
A case study on taming the chaos in design system documentation
This case study explores an eight-month initiative I led to transform our team’s fragmented design system documentation into a structured, collaborative, and sustainable process within Confluence. By auditing, organizing, and streamlining years of accumulated documents, we created a system that’s efficient, intuitive, and built to grow with the HarvardSites Design System.
Designing a Documentation Management System for the HarvardSites Design System
Role: Project Lead
Timeline: Dec 2024 - June 2025
Toolkit: Confluence, Google Sheets, Miro
Overview
This case study details an eight-month initiative I lead to overhaul and systematize our team’s approach to design system documentation management, from the initial recognition of a need for change to the implementation of a structured, efficient, and user-friendly system within Confluence. This process took a considerable amount of time due to the amount of documentation we accumulated over the course of a year when our baby design system was in its infancy.
During this phase of the HarvardSites Design System, everyone hit the ground running, and we were elbows deep in building something great. From this initiative, I was able to design and implement a structured, collaborative, and sustainable process for managing all internal design system documentation.
I. The Problem: Documentation Chaos
Initial Issues
Poor Findability: Content was buried in Google Drive folders with inconsistent naming, making it hard to locate.
Version Control Problems: No clear record of updates or changes or control over those changes.
Duplication & Underutilization: Multiple versions of the same document existed, while other valuable resources went unused.
Lack of Ownership: No designated maintainers to ensure content accuracy and relevance.
Impact on the Team
Slower decision-making due to unclear or outdated information.
Duplicate work when existing resources couldn’t be found.
Inconsistent doc naming = inconsistent team language.
Time wasted searching for the right documents.
Siloed knowledge across individual team members.
II. Discovery & Planning
Our team’s journey began with a collaborative and systematic approach, recognizing that tools and unilateral decisions alone would not solve the problem.
Creating a Master Inventory (The Audit)
Before we could fix our documentation chaos, we had to see exactly what we were dealing with. I went full archaeologist, digging through Google Drive, Confluence, Figma, Miro, and every other tool where our design system artifacts might be hiding. Every document, file, and stray draft went into a single master spreadsheet, complete with its title, location, and author. This artifact became our master inventory of all design system related documentation.
When I shared the master inventory with the team, the reaction was instant buy-in. The sheer scope was eye-opening. This single artifact made the scale of our documentation problem tangible. The master inventory became a reference point and conversation starter, setting the stage for our workshops and making it clear why a more structured system was overdue.
Team Workshops: Collaborative Assessment
With everyone’s workload already full, I wanted this process to feel like a benefit, not an added burden. Once we agreed the documentation problem was real, I led a series of collaborative workshops to address it. These sessions built team ownership, kept decisions collective, and maintained buy-in.
Over multiple workshops, we reviewed every document and tagged it with the OUCH method:
Outdated
Unnecessary (archive)
Current
Have to Write
We decided together:
Which documents to keep, update, or delete.
What “archived” meant in our context (e.g., no longer in use but valuable for historical purposes).
Where archived materials would live.
Why team involvement mattered:
Built shared ownership of the documentation.
Avoided unilateral decisions that could create resentment or confusion.
Ensured we had multiple perspectives on what was useful.
Choosing the Right Tool
Choosing the right tool for any team cannot be a unilateral decision. I wanted the adoption of a new tool and process to be as painless as possible for my team. At the end of the day, it’s all about needs over features, what your team’s needs are and not the features of the tool. In the end, we found Confluence to be the best tool for our team. And this was because it:
-
Was easy for all team members to use.
-
Fit our documentation types.
-
Integrated with existing tools, including Jira.
Another pivotal factor was Confluence’s Smart Links functionality. This feature meant the team didn’t have to build every page directly inside Confluence. Instead, they could create docs in their tool of choice (Google Docs, Figma, Miro, etc.) and simply Smart Link them into the wiki. It was a quick, lightweight step that kept documentation centralized in Confluence without disrupting existing workflows.
III. Building the System
Creating a Stucture & Migration
After we identified Confluence as our tool, I led a collaborative workshop to help the team develop a taxonomy and hierarchical structure that matched the design system’s functional areas. The tool we used for this phase was Miro, to help us identify and label these areas of information and what artifacts belonged there.
We started the processes from a high-level, by grouping documents that we felt belonged together. Nothing too complicated, just general intuition. Because the goal of this exercise was to identify what structure is most intuitive to the team. Any documentation we were uncertain about, we placed in a temporary “parking lot” area. In other words, we “UX’ed” our own documentation.
Then we zoomed in. At this point, we organized our documentation into eight big buckets: Requirements, Operations, Communications, Component Library, Design Variations, Research, Accessibility, and Learning Resources. Each one represents a core function of the design system. But how do we organize within those areas of information?
Collaborative Affinity Mapping
We used Miro to cluster and sort documentation together as a team. This exercise helped us:
-
Identify overlaps and redundancies
-
Spot gaps where content was missing
-
Build shared understanding of our documentation landscape
Within each bucket, we created a sub-level structure to keep things consistent: Planning, Workflows & Process, Artifacts, and Management. This gave us a repeatable pattern no matter the topic.
A large part of the discussion was clarifying what we meant by an artifact. Together, we defined it as a document created out of workflows, processes, or planning documentation, the tangible output that results from our work. That definition helped us separate “how we do the work” (planning, process, workflows, and management) from “what comes out of the work” (artifacts).
A smaller example of the visual hiearchy the HarvardSites Design System team developed together to organize the design system's documentation in Confluence.
A process diagram illustrating the documentation structure developed by the HarvardSites design system team. The flow moves through four phase, planning, process, artifact, and management, each paired with an example of the documentation type relevant to that stage.
Custodianship: A Sense of Ownership
As we were setting up the new documentation system, I introduced the idea of custodianship, giving each document or category a clear steward. The point wasn’t to add extra work, but to make sure our documentation stayed accurate and useful without falling through the cracks. To align the team, I led a workshop on what custodianship means and why it mattered. We discussed how having a designated custodian helps avoid outdated content, gives the team a clear point of contact, and makes documentation easier to trust.
When I first introduced custodianship, the team’s biggest concern was that it would turn into just another responsibility piled onto their already full plates. To ease their concerns, I framed custodianship not as a job, but as a time-saver. Instead of everyone wondering “Who’s supposed to update this?” or digging around to find the latest version, custodianship made the answer clear. Each custodian acts as a steward, not the sole content creator.
Custodianship resposibilities included:
-
Keeping an eye on documents in their area.
-
Making sure they weren’t outdated or duplicated.
-
Pointing the team in the right direction when questions arise.
In practice, this meant fewer information silos, less wasted time, and more confidence that our documentation was something we could rely on. By making custodianship a light-touch responsibility, we turned what could have felt like “extra work” into a simple structure that ultimately made everyone’s lives easier. Instead of assigning responsibilities top-down, I created a poll so team members could choose which areas they wanted to take on. This gave everyone agency to decide where they felt most comfortable or knowledgeable.
IV. Formalizing the Process
Documenting the Process
Once the team finished workshopping a structure and assigned custodianship, the next step was to document the process. I created a design system documentation management guide that captured our decisions, standards, and workflows in one place. The goal wasn’t just to write another manual, but to give the team a living reference that:
Ensured accuracy and relevance of documentation over time.
Standardized language, formatting, and terminology across all docs.
Made our structure easy to navigate so anyone could find what they needed.
Provided repeatable workflows for creating, reviewing, and archiving content.
The guide walked the team through every step of managing documentation in Confluence, including:
-
Accessing Confluence: Step-by-step instructions for requesting access and joining the Design System space.
-
Hierarchy & Organization: The high-level categories (Requirements, Operations, Communications, Component Library, Design Variations, Research, Accessibility, Learning Resources) and their sub-levels (Planning, Workflows & Process, Artifacts, Management).
-
Creating New Documentation: Clear criteria for deciding if a document belongs in Confluence, and a template for new pages to keep formatting consistent. We also leveraged Confluence’s Smart Links feature, which allowed the team to link in Google Docs, Figma files, or Miro boards directly.
-
File Naming Best Practices: Guidelines for clarity, conciseness, and versioning.
-
Version Control & Archiving: How to use Confluence’s version history, when and how to archive, and a bi-annual clean-up process.
-
Custodianship: A record of custodian assignments and responsibilities, ensuring accountability for every area.
-
Feedback Loop: A process for the team to suggest improvements, ensuring the process stays relevant and adaptable.
V. Rollout & Adoption
With the structure, custodianship, and process guide in place, the next step was rolling it out to the team. We set a clear go-live date so everyone knew when the transition would happen and had time to prepare. To support the rollout, I led an onboarding workshop where I walked the team through:
-
The new Confluence space and how to navigate it.
-
How to create new documentation using templates and Smart Links.
-
Where to find existing docs in the new hierarchy.
-
What custodianship meant in practice, and how to flag updates or issues.
We kept the rollout simple and collaborative. Instead of dumping everything on the team, I migrated our documentation in phases: starting with high-priority documents, then gradually migrating less-used or archived content. This phased approach kept the transition from feeling overwhelming.
The implementation wasn’t just about turning on a new tool. It was about creating confidence. By the end of the rollout, the team knew where to go for information, how to add to it without disrupting their workflows, and who to go to if something needed attention.
VI. Conclusion
What started as a scattered collection of documents across multiple platforms became a structured, collaborative, and sustainable system for managing our design system knowledge. By leading the team through audits, workshops, custodianship, and the creation of a management guide, I helped transform documentation from a source of frustration into a resource the entire product team could rely on.
The impact was immediate:
42
unused documents archived across 4 platforms
100%
of documents have clear ownership
100%
of documents smart linked in Confluence
100%
reduction in duplicated and conflicting documents
Before the new system, finding the right documentation could take anywhere from 15–30 minutes, if it could be found at all. With the new structure, those searches now take seconds.
-
Weekly savings: Across a 12-person team, even saving just 15 minutes per person per week amounts to 3 hours reclaimed.
-
Reduced duplication: By cutting 42 unnecessary or outdated documents, we eliminated redundant work and rework cycles.
-
Streamlined onboarding: New team members can now ramp up faster, since they won't have to waste time digging through multiple platforms.
What used to feel like a frustrating scavenger hunt is now a simple, predictable flow. The shift freed up hours each month that the team could reinvest into design, research, and development rather than wrestling with documentation. This project reinforced an important lesson: tools alone don’t fix documentation, people do. By focusing on collaboration first and building a process that worked for our team, we created a system that not only solved our immediate pain points but will continue to grow with us.
Key Takeaways
-
Start with collaboration, not enforcement. Team buy-in matters more than the tool.
-
Tools matter, but people matter more. The platform only works if the team is aligned on its purpose and use.
-
Documentation should serve the team, not burden them. The process must support efficiency, not create busy work.