Lesson 9 / الدرس 9
Documentation people actually read / توثيق يقرؤه الناس فعلًا
Most design system documentation is written to be complete and read by nobody. The version that gets used answers one question — "can I use this here?" — in the ten seconds someone has before they give up and build their own.
معظم توثيق أنظمة التصميم يُكتب ليكون شاملًا ولا يقرؤه أحد. أما النسخة التي تُستخدم فتجيب عن سؤال واحد — «أأستطيع استخدام هذا هنا؟» — في العشر ثوانٍ التي يملكها أحدهم قبل أن ييأس ويبني واحدًا خاصًا به.
Somebody is mid-task with a deadline. They think there might be a component for this. They have about ten seconds of patience before building their own is faster. Every decision about documentation should be made for that person, not for the imaginary reader who sits down to study the system.
What each component page needs
-
What it is for, in one sentence, at the very top. Most visits end here, and that is a success rather than a failure. غرضه، في جملة واحدة، في الأعلى تمامًا. فمعظم الزيارات تنتهي هنا، وهذا نجاح لا إخفاق.
-
When to use something else. The single most valuable line on the page, and the one almost every system omits. متى يُستخدم غيره. وهو أثمن سطر في الصفحة، وأكثر ما تغفله الأنظمة جميعًا تقريبًا.
-
A live example you can copy. Not a screenshot — something that can be taken and pasted, because that is what the person is there to do. مثال حيّ يمكن نسخه. لا لقطة شاشة — بل شيء يمكن أخذه ولصقه، لأن هذا ما جاء الشخص ليفعله.
-
The states, visible together. One row, labelled, so nobody has to guess what focus looks like. الحالات، ظاهرة معًا. صفٌّ واحد معنون، فلا يضطر أحد إلى تخمين شكل التحديد.
-
Accessibility notes, where the component has requirements a developer would not guess — a label, a role, a keyboard behaviour. ملاحظات إتاحة الوصول، حيث يكون للمكوّن متطلبات لا يخمّنها مطوّر — تسمية، أو دور، أو سلوك بلوحة مفاتيح.
<div style="font-family:system-ui; max-width:420px; font-size:14px; line-height:1.6">
<h2 style="margin:0 0 4px">Button</h2>
<p style="margin:0 0 12px">Triggers an action on the current page.</p>
<p style="margin:0 0 12px; padding:10px 12px; background:#fdf5e6;
border-inline-start:3px solid #cb9432">
<strong>Use a link instead</strong> when it navigates somewhere. If the
browser back button should return from it, it is a link.</p>
<p style="margin:0 0 4px"><strong>Variants</strong></p>
<p style="margin:0 0 12px; color:#5b6478">primary — the main action, one per screen<br>
secondary — an alternative to the primary<br>
danger — destructive and irreversible</p>
<p style="margin:0 0 4px"><strong>Accessibility</strong></p>
<p style="margin:0; color:#5b6478">Needs a visible focus state. If the label is
an icon only, it needs an accessible name.</p>
</div>Documentation rots
A page describing how a component behaved a year ago is worse than no page, because it is trusted. The only documentation that stays true is documentation rendered from the thing itself — a live example that breaks when the component breaks, rather than a screenshot that keeps showing last year's design forever. Where you must write prose, keep it to the parts that change least: what it is for, and when not to use it.
Try it live / جرّب بنفسك
Check yourself / اختبر نفسك
1. Who should component documentation be written for?
The studying reader is rare and patient; the mid-task reader is common and about to bypass the system. Writing for the second serves both, and it is the moment adoption is actually won or lost.
2. Which line prevents the most misuse?
Describing what a component does cannot stop someone using it for the wrong job. Naming the boundary and the alternative does, in one sentence, and almost every system omits it.
3. Why is a screenshot poor documentation for a component?
A live example fails visibly when the component changes; a screenshot silently becomes a lie. Documentation that cannot rot is worth far more than documentation that is thorough today.
Score / النتيجة: 0 / 3
Your task / مهمتك
Write the documentation page for one component you designed earlier in this course. It must be readable in ten seconds, and the "use something else when" line must sit directly under the description.
اكتب صفحة توثيق لمكوّن واحد صمّمته سابقًا في هذه الدورة. ويجب أن تُقرأ في عشر ثوانٍ، وأن يقع سطر «استخدم غيره حين» تحت الوصف مباشرة.
- One sentence saying what it is for, at the top جملة واحدة تقول غرضه، في الأعلى
- A "use something else when" line, naming the alternative سطر «استخدم غيره حين»، يسمّي البديل
- A live example, and the states shown together and labelled مثال حيّ، والحالات معروضة معًا ومعنونة
- Accessibility notes for anything a developer would not guess ملاحظات إتاحة وصول لكل ما لا يخمّنه مطوّر