كان لموقع التوثيق الأول في Northwind 140 صفحة، وخط جميل، وقسم مبادئ استغرقت كتابته شهرًا. لكن التحليلات روت لنا قصة متواضعة: في صفحات المكوّنات كان وسيط مدّة الزيارة 38 ثانية. يصل الناس، ويمرّرون إلى أول كتلة كود، وينسخونها، ويغادرون. أما قسم المبادئ فكان متوسط زياراته تسعًا في الأسبوع، معظمها من فريقنا نحن.
\nهذا ليس تقصيرًا من القرّاء. المهندسون والمصمّمون يفتحون التوثيق في منتصف مهمّة ومعهم سؤال واحد: «هل هذا هو المكوّن الصحيح، وكيف أستخدمه؟». التوثيق الجيد يجيب عن ذلك في الشاشة الأولى، ويُبقي كل ما عداه على بُعد تمريرة واحدة.
\nكل صفحة مكوّن في Northwind تتبع الترتيب نفسه، فيتعلّم الناس أين ينظرون:
\nDialog.Title»).هذا الترتيب يتبع ما يحتاجه الناس تحت ضغط الوقت. القرار («هل أستخدم هذا؟») والمثال القابل للنسخ يأتيان أولًا؛ والمواد المرجعية تأتي أخيرًا.
\n\nجزءان في صفحة التوثيق يتقادمان أسرع من غيرهما: جداول الـ props وأمثلة الكود. وكلاهما يمكن أن يأتي من الكود. جداول الـ props تُولَّد من أنواع TypeScript. والأمثلة تأتي من الـ stories، وهي الملفات نفسها المستخدمة في التطوير والاختبارات البصرية. في Storybook، ملف الـ story الذي يحمل الوسم autodocs يحصل على صفحة توثيق مولَّدة فيها معاينة حيّة، وكود الـ story، وجدول controls مبني من الـ props الخاصة بالمكوّن:
import type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Button } from './Button';\n\nconst meta = {\n component: Button,\n tags: ['autodocs'],\n args: { children: 'Assign driver' },\n} satisfies Meta<typeof Button>;\nexport default meta;\n\ntype Story = StoryObj<typeof meta>;\n\nexport const Secondary: Story = {};\nexport const Primary: Story = { args: { variant: 'primary' } };\nexport const Danger: Story = { args: { variant: 'danger', children: 'Delete route' } };\nexport const Small: Story = { args: { size: 'sm' } };ما لا يستطيع الكود توليده هو الحكم: متى تستخدم المكوّن، ومتى لا تستخدمه، وكيف تصوغ محتواه، ولماذا اتّخذ النظام قراراته. وهناك يذهب وقت الكتابة لدى فريق التوثيق.
\n\nالتوثيق الذي يُطلَق لاحقًا لا يُطلَق أبدًا. قالب الـ pull request لمكوّنات النظام في Northwind فيه قائمة فحص: stories لكل variant وكل حالة، وصفحة توثيق محدّثة، وقسم لإمكانية الوصول، وإدخال في الـ changelog. وأي تغيير في مكوّن بدونها لا يُدمج. ولأن التوثيق يعيش في المستودع نفسه مع المكوّنات، يُراجَع في الـ pull request نفسه ومن الأشخاص أنفسهم.
\nثم عامل التوثيق كمنتج. تتابع Northwind ثلاث إشارات: عمليات البحث التي لا تعيد نتائج، والأسئلة المطروحة في قناة نظام التصميم على Slack، والصفحات التي ترتفع فيها نسبة المغادرة مباشرة بعد قسم «متى تستخدمه». كل سؤال متكرّر يصبح تغييرًا في التوثيق. وإن وصل السؤال نفسه ثلاث مرات، فمكان الإجابة هو الصفحة، لا سلسلة رسائل.
\n\nفي التمرين تخطّط لإصلاحات التوثيق خلف إساءة استخدام حقيقية. وبهذا يكتمل قسم المكوّنات؛ وبعده تربط جانب التصميم بجانب الكود في النظام حتى يبقيا متزامنين.
\n","toc":[{"id":"sec-1","text":"تشريح صفحة المكوّن","level":2},{"id":"sec-2","text":"ولّد ما ينحرف، واكتب ما لا يمكن توليده","level":2},{"id":"sec-3","text":"التوثيق جزء من «المنجَز»","level":2}],"takeaways":["يمسح الناس التوثيق بحثًا عن مثال قابل للنسخ وعن إجابة بنعم أو لا على سؤال «هل أستخدم هذا؟»، فضع هذين أولًا.","كل صفحة مكوّن تحتاج قسمَي «متى تستخدمه» و«متى لا تستخدمه»، مع روابط إلى البديل الصحيح.","ولّد جداول الـ props والأمثلة من الكود والـ stories حتى لا تنحرف؛ واكتب يدويًا فقط ما لا يستطيع الكود التعبير عنه.","التوثيق جزء من تعريف «المنجَز»، ويُطلَق في الـ pull request نفسه الذي يحمل تغيير المكوّن."],"further":[{"title":"Writing docs with Autodocs (Storybook, official repository docs)","url":"https://github.com/storybookjs/storybook/blob/next/docs/writing-docs/autodocs.mdx"},{"title":"How Users Read on the Web (Nielsen Norman Group)","url":"https://www.nngroup.com/articles/how-users-read-on-the-web/"},{"title":"Button component page (U.S. Web Design System)","url":"https://designsystem.digital.gov/components/button/"}],"quiz":[{"q":"تُظهر التحليلات أن معظم زوّار صفحة Button في Northwind يغادرون خلال 40 ثانية بعد نسخ أول مثال كود. ماذا تستنتج؟
","options":[{"text":"أن الصفحة فاشلة، ويجب إجبار الناس على قراءة الصفحة كاملة.","why":"الزيارات السريعة غالبًا نجاح، فقد وجد الزائر المثال الذي يحتاجه. وإجبار الناس على القراءة يعاكس طريقة عملهم."},{"text":"أن المثال الأول يجب أن يكون الاستخدام الصحيح الأكثر شيوعًا، مع أهم إرشاد بجانبه مباشرة.","why":"صحيح. إن كان المثال الأول هو ما يُنسخ، فهو الذي يقرّر ما يُطلَق، لذا يجب أن يقدّم القيمة الافتراضية الصحيحة."},{"text":"أن أمثلة الكود يجب أن تُحذف حتى يقرأ الناس الإرشادات.","why":"حذف أكثر ما يحتاجه الناس يدفعهم إلى النسخ من كود منتجات أخرى، بأخطائه."},{"text":"أن الصفحة تحتاج variants أكثر في المثال الأول.","why":"المثال الأول المزدحم أصعب في النسخ الصحيح؛ اعرض الحالة الشائعة أولًا والبقية تحتها."}],"answer":1},{"q":"تستمرّ الفرق في استخدام زر Danger لإجراء «Remove filter»، وهو ليس إجراءً مدمّرًا. أيّ تغيير في التوثيق يساعد أكثر؟
","options":[{"text":"وصف أطول لألوان زر Danger.","why":"تفاصيل الألوان لا تخبر أحدًا متى يكون الـ variant مناسبًا."},{"text":"سطر في جدول الـ props لـvariant="danger".","why":"جدول الـ props يُظهر أن الخيار موجود؛ ولا يقول شيئًا عن متى تختاره."},{"text":"ملاحظة «متى لا تستخدمه» مع مثال افعل/لا تفعل، تشير إلى الـ variant الثانوي للإجراءات القابلة للتراجع.","why":"صحيح. تسمّي إساءة الاستخدام بالضبط وتقدّم البديل لحظة اتخاذ القرار."}],"answer":2},{"q":"جدول props الخاص بـ Button في التوثيق يسرد prop باسم kind أُعيدت تسميته إلى variant قبل إصدارين. ما الإصلاح الدائم؟
يشتكي موظّفو الـ dispatch من أن التطبيق يقاطعهم باستمرار: ست فرق صارت تفتح Dialog يوقف العمل ويقول «Route saved!» بعد كل حفظ. تفحص صفحة توثيق Dialog، فتجدها تبدأ بعرض حيّ لنافذة النجاح هذه بالضبط، يليه جدول props كامل. ولا يوجد أي إرشاد عن متى تستخدم Dialog ومتى تستخدم Toast. أيّ التغييرات ستجريها؟ اختر كل ما ينطبق.
\n","hints":["تذكّر أيّ جزء من الصفحة يُنسخ أكثر من غيره.","الإصلاحات الجيدة تعمل لحظة يقرّر أحدهم أيّ مكوّن يستخدم، داخل صفحة التوثيق نفسها."],"explanation":"المثال الأول هو أكثر كود يُنسخ في الصفحة، فقد كان يعلّم إساءة الاستخدام؛ واستبداله بقرار حقيقي يوقف العمل، مثل «Delete route?»، يغيّر ما يُنسخ. وسطر «متى لا تستخدمه» مع زوج افعل/لا تفعل يسمّيان الخطأ بالضبط ويشيران إلى Toast لحظة اتخاذ القرار. أما مزيد من تفاصيل الـ props، أو رابط إلى المبادئ، أو الردّ على الفرق واحدًا واحدًا في Slack، فتترك الصفحة نفسها بلا تغيير، فيكرّر الفريق التالي الخطأ.
\n","checkLabels":{},"optionText":{"when-not":{"text":"إضافة «متى لا تستخدمه: التأكيدات التي لا تحتاج قرارًا. استخدم Toast بدلًا منه» قرب أعلى الصفحة.","why":"صحيح. يسمّي إساءة الاستخدام والبديل حيث يقرّر الناس."},"props-detail":{"text":"توسيع جدول الـ props بتفاصيل أكثر عنopen وonOpenChange.","why":"الـ props تعمل جيدًا؛ الفرق اختارت المكوّن الخطأ، وهذا ما لا يستطيع جدول الـ props معالجته."},"first-example":{"text":"استبدال المثال الأول بقرار يوقف العمل مثل «Delete route?» مع إجراءَي Cancel وDelete.","why":"صحيح. المثال الأول هو ما يُنسخ، لذا يجب أن يقدّم الاستخدام الصحيح."},"principles":{"text":"إضافة رابط إلى صفحة مبادئ التصميم في أعلى صفحة Dialog.","why":"المبادئ عامة؛ ولن يتبع أحد رابطًا ليعرف هل يجب أن توقف رسالة الحفظ الشاشة."},"do-dont":{"text":"إضافة زوج افعل/لا تفعل: Dialog لـ «Delete route?»، وToast لـ «Route saved».","why":"صحيح. الأمثلة المتجاورة تجعل الحدّ بين المكوّنين واضحًا من النظرة الأولى."},"slack":{"text":"الردّ على كل فريق من الفرق الست على Slack لشرح المشكلة.","why":"يساعد هذه الفرق الست مرة واحدة، لكن الصفحة تظلّ تعلّم الفريق التالي الخطأ نفسه."}}},"words":647,"readMinutes":4}