Documentation Is a Living Thing: How We Talk Informs What We Make

Remember being a child on the playground playing a game and having fun, only for the fun to stop when someone says you’re playing the game wrong or you’ve broken one of the rules? Sometimes, it felt like the rules were being made up on the spot. It’s much more fun when everyone knows all the rules.

Democratizing design

One of my goals with design systems is to democratize access to design. Anyone within an organization should be able to contribute their ideas and have them heard. In product design, a familiar scenario unfolds: a passionate team member shares an idea only to face a barrage of skepticism or rejection due to a lack of shared understanding. This recurring narrative highlights a broader issue — a disconnect of knowledge and communication between collaborators.

You may be familiar with Conway’s Law:

Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization's communication structure. — Melvin E. Conway

In essence, how we talk informs what we make. And what we make informs how we talk.

Access to information, or lack thereof, can shape the trajectory of a business. It’s in these moments that the value of accessible documentation emerges as the transformative force.

Good documentation alleviates frustration — by having all the questions and answers available to everyone.

Communicating effectively in documentation

To make documentation accessible to your target audience, it needs to be understood. Some systems separate documentation for designers and developers — I personally dislike this approach. Which documentation should a product manager read — neither? What about a design technologist - both? Being at the intersection of creativity and technology, design systems documentation should cater to all audiences.

One of the early cornerstones of design systems, outlined in Alla Kholmatova’s *The Language of Modular Design,* mentions the importance of a shared language – where everyone communicates on the same level.

Your documentation should be written in plain language. It should be clear, concise, pertinent, and efficient. Plain language doesn’t mean oversimplifying concepts or being condescending to the reader — it means communicating in a way everyone understands.

Top Tips:

• Try to summarise a concept in a single sentence.
• “Buttons are interactive elements that perform an action when clicked.”
• “Accordions expand to reveal more content.”
• Use visual aids when necessary (and provide non-visual alternatives!)
• A well-labeled diagram is often better at communicating an idea than paragraphs of text.
• Avoid jargon where possible, but don’t be afraid to use technical language where necessary.

Codifying rules in Design Systems

Design systems serve as the rulebook that empowers consistent and effective production. They encompass both straightforward guidelines and nuanced principles. Some rules are easy to convey – like specifying font sizes – while others demand a deeper understanding – like preserving brand identity across diverse applications. Design system documentation is crucial in translating these rules into a comprehensive language.

Moreover, the context in which these rules exist is dynamic. Systems evolve as technologies advance and user preferences shift. A decision that was gospel yesterday might seem outdated tomorrow. Documentation isn't a snapshot in time; it's a living entity.

Regular updates ensure the documentation remains aligned with the current thinking, empowering teams to create innovative solutions while upholding the core principles. In this context, documentation isn't a mere record; it's an ongoing conversation that changes over time.

So, when are we documenting?

One of the questions I’m asked frequently is, ‘When do you document the design system?’.

This question suggests there should be dedicated time to sit and write ‘The Documentation.’ However, I mentioned that documentation isn’t a snapshot in time — it needs to be regularly updated. In reality, we are constantly documenting.

There’s a perception of a finalized piece of literature, which is seen as the documentation where we've canonized the system's decisions. But if we’re presenting the idea that documentation is a living entity, then where does it live? And what kind of entity is it?

Systems are a fungal network, and documentation is a mushroom

Yes, I have just rewatched The Last of Us… stick with me, I’m a fun guy I promise.

Mushrooms are the ‘fruit’ of a fungus. But under the ground, in the mycelium, there are complex networks of hyphae carrying all the information that fungus needs to reproduce and survive. Whilst the fruits can be delicious — or dangerous! — the most fascinating part is what happens under the surface and where the fungus lives.

Design systems, at their core, are not just about the end products; they're about the process. Every step in that process generates a piece of documentation. This spectrum of documentation ranges from ephemeral and transient artifacts to more substantial and enduring ones. Recognizing the breadth of this spectrum is crucial to crafting a cohesive and comprehensive design system.

The artifacts we produce with a design system are our fruit. That’s the stuff above the surface that anyone can see — a public documentation site, a storybook, a component library, etc. But most work that goes into producing those artifacts happens behind the scenes.

Everything we make and interact with whilst working can be seen as some form of document. Some are temporary, others are more permanent, and some are ever-changing.

It might not be the first thing that comes to mind, but all of these things are forms of documentation:

• The product roadmap
• Tickets & stories
• Your calendar
• An organization chart
• Your notes and sketches
• Emails, messages & discussions
• Spike reports
• A11y investigations
• Prototypes
• Code
• Designs
• Specifications
• Diagrams
• Pull requests
• RFCs

These are always happening – every day as part of doing design systems, but they’re not always the first thought when we talk about documentation. By nature, these will always be messy and disorganized as they reflect the creative process. So it’s important that we distill all this information into simpler, well-thought-out artifacts.

The lifecycle of documents

Throughout the process of building design systems, the documents we produce reflect the process. Fragments of the broader system go through their own life cycles.

Temporary insights

From brainstorms and sketches to exploratory prototypes, these fleeting moments capture the dynamic nature of creative thought. While transient, these documents hold valuable insights into the ideation process. Key takeaways can provide a glimpse into the origins of decisions.

Progressive foundations

As ideas develop into tangible assets, the documentation becomes more structured. Design mockups and even initial code commits embody the iterative progression of the design system. These offer a record of the evolution from abstractions into implementations.

Structured collaborations

With ideas taking a firmer shape, collaboration intensifies. Documentation includes user stories, tickets, and project management boards. These artifacts provide a roadmap for translating ideas into actionable tasks, offering insights into how the system matures over time.

Decisions and rationales

The architecture of a design system stems from countless decisions. Recording the reasons behind these choices is pivotal. Requests for Comments (RFCs), design rationale documents, and discussion threads capture the decision-making process. This transparency not only aids in continuity but also invites others to comprehend the legacy of the system's logic.

Specification and guidelines

As the system's components and patterns solidify, so does the system’s documentation. Comprehensive specifications, style guides, accessibility guidelines, and usage documentation bridge the gap between the abstract and the practical. These artifacts form the bedrock of the design system – and are what we traditionally think of as ‘documentation’ – helping to ensure consistency and coherence across the board.

Reflection and evolution

The design system isn't static; it evolves. Post-mortem analyses, retrospectives, and version release notes provide a historical narrative of how the system changes over time.

Bringing the story together

It’s impractical to document everything that ever happens across a generation. We need to establish a process to keep an accurate account of the key moments we go through and our decisions.

Curate

Start by identifying the assets that hold the most critical insights. Not everything needs to be documented, but key turning points, major decisions, and key iterations must be preserved.

Contextualize

Each artifact should be accompanied by relevant context. Why was a particular decision made? How does a specific component fit into the larger ecosystem?

Organize

Organize artifacts in a structured hierarchy that helps users to navigate the documentation seamlessly.

Unify

Keep a consistent format across your documentation. Adhering to a uniform template makes the documentation more user-friendly for repeat reference and quick browsing.

Illustrate

Visual elements, such as diagrams, flowcharts, and screenshots, can communicate complex ideas more effectively than words alone.

Demonstrate & evaluate

Just as the design system components need to be accessible, so does its documentation. Ensure that the documentation is usable by a diverse audience, including those with disabilities.

Update

Just as the design system evolves, so should its documentation. Regularly revisit and update artifacts to reflect the latest decisions, iterations, and insights.

My thoughts on design systems resonate deeply with the need for effective communication and collaboration in creative processes — and less of a focus on the artifacts we produce. Just as a game loses its charm when rules are unclear or arbitrarily changed, the design process can be hindered by a lack of shared understanding. The goal of democratizing design, allowing contributions from diverse viewpoints, is a significant step toward fostering innovation and inclusivity within organizations.

The essence of Conway's Law — that an organization's communication structure influences its system design — emphasizes the relationship between conversation and creation. Accessible documentation is the catalyst for clear communication, reducing frustration and fostering a shared language that transcends roles and backgrounds.

I hope that the importance of documentation as a bridge between creativity and technology becomes evident. The idea is that documentation is not a static entity but a dynamic and evolving conversation, mirroring the organic growth of design systems themselves. Each stage of the collaborative process is reflected in the documents we produce.

To navigate this complex spectrum of documentation, remember these principles:

1. Curate the essential moments
2. Contextualize decisions
3. Be systematic in how you organize thoughts
4. Unify the format
5. Illustrate where words fall short
6. Ensure accessibility
7. Commit to regular updates.

These principles serve as a guideline for nurturing a comprehensive and coherent design system that thrives on collaboration, transparency, and growth.

In essence, the journey of documenting a design system parallels the development of the system itself. Just as a mushroom's fruit is only a fraction of the intricate network beneath, the visible artifacts are only the tip of the iceberg in a design system's story. By recognizing the value of all forms of documentation — from emails and sketches to polished guidelines — I urge you to embrace the entirety of this process in guiding you toward a more harmonious and effective design ecosystem.