🔗 🧠 #19 Better Documentation

Documentation is one of those things we all know we should be doing, but always is the first thing that gets pushed to tomorrow's to-do list. I know I've shipped more designs with incomplete documentation than I care to admit. But after working through many implementation hiccups that could’ve been avoided with better documentation, I've learned my lesson (mostly).

This week, we're tackling the art of good documentation — how to create it without losing your mind, how to structure it so people actually use it, and what pitfalls to avoid. Whether you're explaining your decisions, documenting a complex design system, or just trying to leave breadcrumbs for your future self — these resources will help you turn documentation from a chore into a superpower.

— Jake

TODAY'S EDITION

1. UX Design Documentation Guide

2. Documentation That Drives Adoption

3. Diátaxis Framework

4. Best Design System Documentation Sites

5. Examples of Bad Documentation (And How to Do Better)

RESPECT THE SPECS

As designers, we're all familiar with creating specs and redlining, but comprehensive documentation goes way beyond that. While it might seem like a tedious task you don't have time for (guilty), documenting your design decisions and process brings order to the product development chaos, helps you feel accomplished, and can dramatically improve team collaboration if done right. This practice becomes especially crucial when tackling complex feature sets for enterprise UX workflows with multiple stakeholders and users in the mix.

THE JUICE

Beyond Specs: Design documentation isn't just about what to build — it's about capturing why you made certain decisions, how you arrived at solutions, and what the next steps should be. Think of it as creating a map of your thought process that both you and others can follow.

For Future You: Imagine returning to a project six months from now and instantly understanding your past thinking. Your future self will thank you for leaving breadcrumbs.

Strategy Meets Design: Your documentation represents how you're manifesting the product strategy. It connects high-level intentions with practical design decisions and gets everyone aligned on both purpose and execution.

Sanity Check: Writing down your process is a part of storytelling in design — and learning to spot plot holes before they become problems. By documenting as you go, you naturally QA your own work and avoid missing crucial details.

Documentation Done Right: Whether you use Notion, Figma, Confluence, Carrier Pigeons, or whatever else — be sure to establish a dedicated space for documentation that everyone can access but won't accidentally modify. Create templates to standardize the process and make it a natural part of your workflow rather than an afterthought.

Go From Big to Small: Start with the big picture (flowcharts are your friend) before diving into specifics. Show how new features connect to existing ones, explain entry points, and use matrices to visualize conditional logic and different states.

No Time to Document = No Time to Think: If you're consistently skipping documentation, you're missing a crucial part of the design process. Make it a non-negotiable habit — even if it starts with simple sticky notes on wireframes explaining your choices.

Learn more about documentation

BEYOND THE COMPONENTS

Good documentation transforms abstract design principles into practical tools, but creating documentation that people actually use requires more than just cataloging components. The best documentation bridges the gap between intention and implementation, capturing not just what exists but the how and why behind design decisions.

THE JUICE

The Language Bridge: Folks in different business functions speak different languages. Good documentation bridges this gap, capturing both the "how" and the "why" behind design decisions in a way everyone can understand.

Choose Your Source of Truth: Determining where documentation lives is as important as what goes into it. Whether you build a custom site or leverage existing platforms, what matters is that your documentation meets teams where they work with tools that integrate into their workflows.

Layer Your Information: The most effective documentation is structured to serve different needs simultaneously. Include high-level principles for strategic understanding, detailed specifications for implementation, and clear examples that show the system in action.

Maintain Through Automation: As systems evolve, manual documentation quickly becomes outdated and updating it is a drag. Leading teams build automated processes that keep documentation current, from custom tooling that exports changes from design tools directly to documentation sites to linters that validate documentation for completeness.

Measure What Matters: Look beyond page views to understand how documentation influences behavior. Set concrete goals like system adoption percentages and survey teams to measure productivity improvements when using the system versus working without it.

Create Clear Contribution Paths: Establish contribution guidelines, version control practices, and QA processes that balance centralized governance with team input.

Learn more about adoption

FOUR PATHS TO CLARITY

One of the biggest hurdles of creating good documentation? Trying to do too many things at once. I know we all love a good matrix — so let me show you the Diátaxis framework which offers a refreshingly clear approach by identifying four distinct types of documentation, each serving a specific user need. Rather than a one-size-fits-all documentation smorgasbord, this model helps you craft purposeful content that actually works for folks.

THE JUICE

The Four Quadrants: Diátaxis organizes documentation into four distinct types:

• Tutorials (learning-oriented)

• How-to guides (task-oriented),

• Reference (information-oriented),

• Explanation (understanding-oriented)

Learning vs. Doing: The framework maps documentation along two axes. The vertical axis separates theoretical knowledge from practical action, while the horizontal distinguishes between acquiring new skills and applying existing ones.

Tutorials Done Right: True tutorials aren't just step-by-step guides—they're learning experiences where users develop skills and confidence through practical experience.

How-To Guides With Purpose: Unlike tutorials, how-to guides assume competence and focus on helping users achieve specific goals. They're for people already at work, not studying—like a recipe for someone who already knows how to cook.

Reference Without Distraction: Reference documentation should be neutral, factual, and mirror the structure of what it describes. Like a map or technical diagram, it provides accurate information without interpretation or guidance.

Explanation For Context: This is where you answer "why" questions, provide background, and help users understand the bigger picture. It's the place for perspectives and conceptual exploration—not for action steps.

The Compass in Action: When creating documentation, use the Diátaxis compass to clarify your intentions. Ask: Does this content inform action or cognition? Does it serve the user's acquisition or application of skill? The answers will tell you which type of documentation you're creating.

Start Anywhere: The beauty of Diátaxis is that you don't need to overhaul everything at once. Identify one small improvement you can make right now, do it, and then repeat. Each change will naturally point to the next.

Dive deeper into Diátaxis

STUDY THE MASTERS

As with anything in life, there’s no better way to learn than to imitate those who have paved the way before you. Though the idea of documentation is larger than just design systems, there’s a whole group of people who are building documentation hubs that many different people are expected to consume. There are plenty of nuggets that are transferrable to whatever documentation woes you’re facing today.

THE JUICE

Structure Around User Needs: Design systems are great at organizing information based on what people actually need to accomplish. Look at how they separate reference materials from educational guides, and consider how your documentation could benefit from a similar user-centered organization approach.

Make Updates Visible: The best design systems have clear version history and highlight recent changes prominently. This transparency helps users understand what's changed and why — a practice that can dramatically improve adoption of your documentation regardless of subject matter.

Balance Detail with Digestibility: Notice how design systems use progressive disclosure — showing essential information first with options to dive deeper. This approach prevents overwhelming users while still providing comprehensive information, making it perfect for complex design documentation of any kind. Onboarding 101, really.

Use Visual Hierarchy to Guide: The best design systems use thoughtful visual presentation to help users navigate complex information. Consider how spacing, typography, and color could improve the scanability and usefulness of your own documentation, regardless of what you're documenting.

Explore some design systems

THE WOES OF POOR DOCUMENTATION

Good documentation is essential for communication around your design work. When done well, it helps folks understand your design decisions and serves as a valuable resource for teammates. When done poorly, it can create confusion, frustration, and lifelong enemies. Here are five common documentation mistakes and how to avoid them.

THE JUICE

Ghost Documentation: The worst documentation is the one that doesn't exist or can't be found. If your design decisions, rationales, and specifications aren't documented or are buried deep in your design tool, your team can't benefit from your thinking process. Make documentation discoverable and prominent.

Broken Promises: Inaccurate or outdated documentation can be worse than no documentation at all. When your specs don't match the actual implementation, or your documented patterns don't reflect current design decisions, it creates a trust problem. Regularly audit your documentation for accuracy and update it when things change.

Format Frustrations: Nothing says "I don't care about your experience" like documentation trapped in hard-to-use formats. Whether it's static PDFs that can't be easily searched or copied from, or unstructured slides that lack context, the medium matters. Choose accessible, linkable formats that work for your audience in the context that matters.

One-Dimensional Approach: Reference-only documentation tells what exists but not how to use it effectively. For example, a design system with only component specs but no guidance on patterns, context, or when to use what leaves too many dots unconnected. Include the multiple types of documentation you just learned about: reference, tutorials, explanations, and how-to guides.

No Point of View: Documentation without narrative or opinion lacks the why behind decisions. When you share only how components work without explaining the design principles or thinking that shaped them, you miss an opportunity to build understanding. The most valuable documentation shares your design perspective and reasoning.

More about bad documentation

THANKS FOR READING—SEE YOU NEXT WEEK

In the meantime, feel free to:

1. Forward this email or share this link with your friends if you feel they need some links for thinks: https://www.linksforthinks.com/subscribe

2. Reach out with any suggestions or questions for the newsletter.

3. Send me some of your favorite links and takeaways.

Cheers, Jake