Designing the system behind the system
Bringing structure to a system that was starting to bury itself
Role: Design System Lead
Scope: Design systems, documentation, governance, product work
THE PROBLEM
Harvard Web Publishing (HWP) was in the middle of a significant platform migration, moving from OpenScholar, a legacy system built on Drupal 7 and used by thousands of sites across Harvard's schools, departments, and research centers, to HarvardSites, a modern Drupal CMS built to support the university at scale. The migration affected faculty, researchers, students, site visitors, and site builders across the institution, and the timeline was tight. Every decision the design system team made had downstream implications for hundreds of sites.
In that environment, the HarvardSites Design System was built fast. That was the right call. But documentation didn't keep pace. Over the course of a year, files accumulated across Google Drive, Confluence, Figma, and Miro with no consistent naming conventions, no clear ownership, and no shared sense of what was current versus outdated. Finding the right document could take 15–30 minutes, if it could be found at all. Duplicate files created conflicting sources of truth. Valuable resources went unused because no one knew they existed. And when new team members joined, there was no reliable place to point them to.
In the push to build something operable under real time pressure, nobody had stopped to build a system for the system.
THE CONSTRAINTS
This initiative was entirely self-directed. Before any work could begin, I needed the team to recognize the problem the same way I did. That meant the first meeting wasn't a kickoff, it was a listening session. I asked the team about their current experience finding and using documentation, and let the pain points surface on their own. The case for change had to come from them, not from me.
The team was already at full capacity building the design system itself. Any governance initiative that felt like overhead, extra meetings, new tools to learn, responsibilities piled on top of existing ones, would lose momentum before it gained any. Every decision I made throughout this project was filtered through a single question: does this make their lives easier, or harder?
DECISION POINTS
Decision #1: Run the buy-in meeting as a discovery session
What I noticed
Before I could fix anything, I needed the team to validate my theory that our current situation was a blocker. I opened the first workshop not with a plan, but with a question: what is your experience actually like trying to find what you need? The answers came quickly, and they confirmed what I suspected. People were losing time, duplicating work, and losing trust in the documentation they did manage to find.
From that conversation, I built a master inventory that recorded every document across every platform, its location, its creator, and its apparent status. When I shared it with the team, the reaction was immediate. Seeing 70+ documents laid out in a single spreadsheet made the scale of the problem undeniable, and it made the case for action better than any proposal I could have written.
The choice we made
I designed a series of workshops where the full team reviewed every document together using a shared classification method called OUCH: Outdated, Unnecessary (archive), Current, Have to Write. Nothing got moved or deleted without a team conversation first.
Why that choice was made
Documentation governance fails when it's imposed top-down. If I had triaged documents alone, I would have inevitably flagged something as outdated that someone else relied on and lost the team's trust in the process before it started. The workshops turned a potential source of friction into a source of ownership. By the time we finished the audit, the team had collectively touched every document, which meant they understood the new system because they'd helped build it.
Example design system documentation structure for Confluence developed by the HarvardSites design system team.
Decision #2: Design the taxonomy the way you'd design a product
What I noticed
Once we knew what we had, we needed somewhere logical to put it. The instinct was to jump into Confluence and start creating folders,, but folder structures built by one person reflect one person's mental model. I'd seen this fail repeatedly in user research. The way people expect to find something rarely matches the way it was organized. That's a UX problem, and it applied here as much as anywhere else.
The choice I made
Instead of designing the structure myself, I ran a Miro-based affinity mapping workshop. We grouped documents by intuition first; no framework, no labels. Then we zoomed out and named the clusters. Eight high-level categories emerged, each with a consistent sub-level pattern: Planning, Workflows & Process, Artifacts, and Management.
Why that choice was made
Running the exercise as a team meant the final structure reflected how everyone thought about the work, not just how I did. It also meant adoption was built in from the start. People find things more easily in systems they helped create.
Decision #3: Make custodianship feel like less work, not more
What I noticed
A well-structured documentation system degrades without maintenance. Without someone paying attention to each area, documents go stale, ownership gets murky, and you're back to chaos inside a year. The solution was custodianship, giving each document category a named steward. But when I introduced the idea, the initial response was expected: this sounds like more work.
The concern was legitimate. Nobody on a design system team is looking for another responsibility on top of an already full plate. If custodianship felt like a job on top of a job, it would be quietly ignored.
The choice I made
I reframed custodianship as a clarity tool, not a workload. A custodian isn't the sole author of everything in their area. They're the person who knows the state of it and can point others in the right direction. To give the team agency in how responsibilities were distributed, I used a poll rather than top-down assignment, letting people self-select into the areas where they felt most knowledgeable or invested.
Why that choice was made
Self-selection matters for sustainability. When someone chooses their area, they're more likely to stay engaged with it over time. And by framing the role as steward rather than owner, the time investment stayed reasonable. The result was 100% of documents with a named custodian, not because it was required, but because my team understood why it mattered and had a say in how it worked.
Example design system documentation structure for Confluence developed by the HarvardSites design system team.
OUTCOMES
The eight-month initiative turned a scattered collection of files into a structured, maintained system the whole team could navigate with confidence.
42 unused documents archived across four platforms
100% of documents assigned a named custodian
All active documentation centralized in Confluence via Smart Links
Document search time reduced from 15–30 minutes to seconds
Phased rollout kept the transition manageable without disrupting ongoing work
The system was built to grow with the design system, not become another artifact the team would eventually need to remediate.
The final Confluence space for HarvardSites design system documentation.
REFLECTION
I spend most of my time thinking about how users experience products. This project was a reminder that the same thinking applies inward. The team's relationship to its own documentation is a user experience problem, one with the same pain points as any poorly designed product: things are hard to find, ownership is unclear, the language is inconsistent, and there's no feedback loop.
The intervention that worked wasn't more tooling or cumbersome processes. It was treating the team as users, understanding what was getting in their way, and designing a process they'd actually want to use. That's the same approach I have for our users. The only difference was the audience.