<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Donya Aali on Medium]]></title>
        <description><![CDATA[Stories by Donya Aali on Medium]]></description>
        <link>https://medium.com/@donyaaliy.design?source=rss-92815ed3def2------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*WiuH5PB2h6DimHF_-qkl_w.png</url>
            <title>Stories by Donya Aali on Medium</title>
            <link>https://medium.com/@donyaaliy.design?source=rss-92815ed3def2------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 01:26:05 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@donyaaliy.design/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[We Thought Our Design System Documentation Was Good. Our Users Disagreed.]]></title>
            <link>https://medium.com/@donyaaliy.design/we-thought-our-design-system-documentation-was-good-our-users-disagreed-459721b5e28c?source=rss-92815ed3def2------2</link>
            <guid isPermaLink="false">https://medium.com/p/459721b5e28c</guid>
            <category><![CDATA[product-design]]></category>
            <category><![CDATA[case-study]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[documentation]]></category>
            <dc:creator><![CDATA[Donya Aali]]></dc:creator>
            <pubDate>Thu, 18 Jun 2026 09:56:50 GMT</pubDate>
            <atom:updated>2026-06-18T09:56:50.038Z</atom:updated>
            <content:encoded><![CDATA[<p>How a simple survey revealed a deeper issue: our documentation wasn’t wrong — it was optimized for us, not for the people using it</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*i23_3klfvN7tFlHJXN7QUQ.jpeg" /></figure><p>A few months after publishing our Design System documentation, something didn’t add up. Designers kept asking questions that were already documented. Developers kept reaching out about component states and implementation details that were clearly written in the docs.</p><p>At first, the explanation felt obvious: People just weren’t reading the documentation.</p><p>We had spent weeks writing guidelines, documenting components, adding examples, and organizing everything carefully. So if people still had questions, the problem had to be adoption — not the content. But after hearing the same questions repeatedly, that explanation started to feel too simple. Maybe people weren’t ignoring the documentation. Maybe the documentation wasn’t helping them. That question changed how we looked at everything.</p><p><strong>The Documentation Looked Complete (From Our Side).</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wLnC8P8lkOzVFhAWxjDt2Q.jpeg" /></figure><p>Like many Design System teams, we started by documenting components one by one.</p><p>Each page included:</p><ul><li>Usage guidelines</li><li>Variants and states</li><li>Do’s and Don’ts</li><li>Visual examples</li><li>Implementation details</li></ul><p>We followed patterns from established systems like Material Design and other public Design Systems. Structurally, everything felt correct. But there was a hidden issue we didn’t notice at the time: ‘ The Do’s and Don’ts were heavily inspired by Material Design and similar systems — not based on the actual needs and edge cases of our product.’</p><p>That meant that in many situations, designers couldn’t actually find answers to their questions in the documentation, because the documentation simply didn’t cover their real problems.</p><p>From our perspective, the system was “complete”. But from the users’ perspective, it often wasn’t answering their questions at all.</p><p><strong>We Stopped Assuming and Started Asking.</strong></p><p>Instead of guessing, we ran a short survey and interviewed designers and developers across teams. We wanted to understand:</p><ul><li>How they actually used the documentation</li><li>What they searched for when they opened it</li><li>What forced them to ask the DS team anyway</li><li>What they expected but didn’t find</li></ul><p>We also looked at internal support requests. A clear pattern emerged:</p><p>Even when documentation existed, people often defaulted to Slack or asking teammates instead of using it. Not because the answer wasn’t there — but because finding it wasn’t fast enough.</p><p><strong>The Documentation Was “Complete”, But Not Clear</strong></p><p>As we started reviewing the content more critically, another problem became obvious. Some parts of the documentation were simply too long and hard to understand. We had written detailed explanations for almost every component and behavior, but the result was heavy, verbose, and difficult to scan.</p><p>So we went back and did a full content pass:</p><p>We simplified the language, reduced unnecessary explanations, and rewrote sections to be shorter, clearer, and more direct.</p><p>This alone made a noticeable difference in readability.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NsQUiof1P0Tx7tODU27fDA.jpeg" /></figure><p><strong>We Had One Documentation. We Actually Had Two Audiences.</strong></p><p>One conversation changed our direction completely.</p><p>A developer told us:</p><blockquote>“When I implement a component, I need everything in one place. I don’t want to jump between Figma, code, and multiple pages.”</blockquote><p>We showed him a proposed specification table (colors, spacing, typography, states, props). His response was immediate:</p><blockquote>“I would use this every day.”</blockquote><p>Then he added something important:</p><p>“We don’t really read Do’s and Don’ts.” That wasn’t a rejection of the content. It was a mismatch of purpose.</p><p>Do’s and Don’ts were written with Material Design patterns in mind — but they weren’t aligned with how our product actually behaved. So they weren’t answering the real questions designers had.</p><p>That was a key realization: Designers were using Do’s and Don’ts to make decisions. But those decisions weren’t covered in a way that matched our product reality. Developers, on the other hand, needed structured specifications for implementation. We had merged both needs into a single experience — and it served neither well.</p><p>So we separated them. We introduced two distinct layers:</p><p>***Specification layer** → technical implementation details</p><p>***Guidelines layer** → design decisions and usage intent</p><p>What started as a documentation task turned into an information architecture problem.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nrm3NHPTC4V99yXjfRm8pQ.jpeg" /></figure><p><strong>The Language Problem We Didn’t Expect</strong></p><p>During interviews, a designer said something simple:</p><blockquote>“Reading English takes extra effort for me.”</blockquote><p>At first, it didn’t seem critical. The documentation wasn’t complex, and most people on the team understood English. But the issue wasn’t comprehension. It was friction. When people need a quick answer, even small amounts of friction change behavior.</p><p>The same designer explained:</p><blockquote>“If I need something fast, I’d rather ask someone than read a long page in English.”</blockquote><p>That explained a lot of our support behavior. Documentation doesn’t compete with other documentation. It competes with the fastest available alternative.</p><p><strong>We Organized by Components. Users Thought in Problems.</strong></p><p>Our structure was familiar:</p><p>Button. Input. Checkbox. Dropdown, etc. It matched how the system was built. But users weren’t thinking in components.</p><p>They were thinking in questions:</p><ul><li>Which variant should I use here?</li><li>What should happen when validation fails?</li><li>What’s the correct behavior in this flow?</li></ul><p>We were documenting components. They were looking for decisions.</p><p><strong>Not Everything Needed Documentation</strong></p><p>Another insight came from observing workflows more closely. Some information was already discoverable:</p><ul><li>Figma components</li><li>Code implementation</li><li>Visible UI behavior</li></ul><p>But some critical information wasn’t:</p><ul><li>Edge-case behavior</li><li>Hidden states</li><li>Spacing logic</li><li>System-level decisions</li></ul><p>That became our focus. Instead of documenting everything equally, we started prioritizing what users couldn’t infer on their own.</p><p><strong>We Prototyped the Documentation Itself</strong></p><p>One of the biggest structural changes we made was treating the documentation as a product, not just a set of pages. To support this, we even prototyped the documentation experience itself.</p><p>The goal was simple:</p><p>Make it easier for users to navigate between different parts of the documentation based on their needs.</p><p>Instead of forcing users to follow a linear structure, we designed it so they could move between sections as they would in a product interface — jumping between specs, guidelines, and examples depending on their intent.</p><p>This helped us validate something important:</p><p>Navigation mattered as much as content.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KtXtOa_k1Ph1x7mfRgssJg.jpeg" /></figure><p><strong>What Changed</strong></p><p>After restructuring:</p><ul><li>Specification content moved into dedicated tables</li><li>Guidelines became decision-focused pages</li><li>Language was simplified and rewritten for clarity</li><li>Documentation navigation was prototyped for better exploration</li></ul><p>Over time, we observed:</p><ul><li>Fewer repetitive questions in Slack</li><li>More self-serve usage of documentation</li><li>Reduced dependency on the DS team for basic implementation questions</li></ul><p>We didn’t eliminate questions. But we reduced the number of questions that documentation was supposed to answer. That was the signal.</p><p><strong>Final Thoughts</strong></p><p>Looking back, the problem was never a lack of documentation. We had plenty of it.</p><p>The problem was that we optimized for completeness instead of usability. We documented what we thought people should know. Instead of understanding what they were trying to do.</p><p>The shift happened when we stopped treating documentation as a collection of pages — and started treating it as a product.</p><p>A product with users, constraints, and competing alternatives.</p><p>And like any product, it only works when it solves real user intent faster than everything else available.</p><p><strong>If there’s one principle we keep coming back to</strong></p><p>**Don’t structure documentation around what you built.</p><p>**Structure it around the questions people are trying to answer.**</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=459721b5e28c" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>