توثيق يقرؤه الناس فعلًا

كان لموقع التوثيق الأول في Northwind 140 صفحة، وخط جميل، وقسم مبادئ استغرقت كتابته شهرًا. لكن التحليلات روت لنا قصة متواضعة: في صفحات المكوّنات كان وسيط مدّة الزيارة 38 ثانية. يصل الناس، ويمرّرون إلى أول كتلة كود، وينسخونها، ويغادرون. أما قسم المبادئ فكان متوسط زياراته تسعًا في الأسبوع، معظمها من فريقنا نحن.

هذا ليس تقصيرًا من القرّاء. المهندسون والمصمّمون يفتحون التوثيق في منتصف مهمّة ومعهم سؤال واحد: «هل هذا هو المكوّن الصحيح، وكيف أستخدمه؟». التوثيق الجيد يجيب عن ذلك في الشاشة الأولى، ويُبقي كل ما عداه على بُعد تمريرة واحدة.

تشريح صفحة المكوّن

كل صفحة مكوّن في Northwind تتبع الترتيب نفسه، فيتعلّم الناس أين ينظرون:

1. وصف من سطر واحد لما وُجد المكوّن من أجله.
2. متى تستخدمه، ومتى لا تستخدمه، مع روابط إلى البديل. «استخدم Dialog للقرارات التي توقف المهمّة الحالية. وللرسائل التي لا توقفها، استخدم Toast».
3. المثال الأساسي: عرض حيّ للاستخدام الصحيح الأكثر شيوعًا، مع كود قابل للنسخ.
4. أمثلة لكل variant ولكل حالة مهمّة، لكلٍّ منها كودها الخاص.
5. إمكانية الوصول: سلوك لوحة المفاتيح، وما تعلنه قارئات الشاشة، وفصل بين ما يتولّاه المكوّن وما يجب أن يفعله الفريق بنفسه (مثل «يجب أن تعطي كل Dialog عنصر Dialog.Title»).
6. إرشادات المحتوى: كيف تكتب التسميات والرسائل. «تسميات الأزرار تبدأ بفعل: Assign driver، لا Driver assignment».
7. جدول الـ props، مولَّدًا من الكود.
8. الحالة والتاريخ: مستقر أو beta أو deprecated؛ والإصدار الذي أُضيف فيه؛ وروابط إلى الـ changelog.

هذا الترتيب يتبع ما يحتاجه الناس تحت ضغط الوقت. القرار («هل أستخدم هذا؟») والمثال القابل للنسخ يأتيان أولًا؛ والمواد المرجعية تأتي أخيرًا.

ولّد ما ينحرف، واكتب ما لا يمكن توليده

جزءان في صفحة التوثيق يتقادمان أسرع من غيرهما: جداول الـ props وأمثلة الكود. وكلاهما يمكن أن يأتي من الكود. جداول الـ props تُولَّد من أنواع TypeScript. والأمثلة تأتي من الـ stories، وهي الملفات نفسها المستخدمة في التطوير والاختبارات البصرية. في Storybook، ملف الـ story الذي يحمل الوسم autodocs يحصل على صفحة توثيق مولَّدة فيها معاينة حيّة، وكود الـ story، وجدول controls مبني من الـ props الخاصة بالمكوّن:

import type { Meta, StoryObj } from '@storybook/react-vite';
import { Button } from './Button';

const meta = {
  component: Button,
  tags: ['autodocs'],
  args: { children: 'Assign driver' },
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Secondary: Story = {};
export const Primary: Story = { args: { variant: 'primary' } };
export const Danger: Story = { args: { variant: 'danger', children: 'Delete route' } };
export const Small: Story = { args: { size: 'sm' } };

ما لا يستطيع الكود توليده هو الحكم: متى تستخدم المكوّن، ومتى لا تستخدمه، وكيف تصوغ محتواه، ولماذا اتّخذ النظام قراراته. وهناك يذهب وقت الكتابة لدى فريق التوثيق.

التوثيق جزء من «المنجَز»

التوثيق الذي يُطلَق لاحقًا لا يُطلَق أبدًا. قالب الـ pull request لمكوّنات النظام في Northwind فيه قائمة فحص: stories لكل variant وكل حالة، وصفحة توثيق محدّثة، وقسم لإمكانية الوصول، وإدخال في الـ changelog. وأي تغيير في مكوّن بدونها لا يُدمج. ولأن التوثيق يعيش في المستودع نفسه مع المكوّنات، يُراجَع في الـ pull request نفسه ومن الأشخاص أنفسهم.

ثم عامل التوثيق كمنتج. تتابع Northwind ثلاث إشارات: عمليات البحث التي لا تعيد نتائج، والأسئلة المطروحة في قناة نظام التصميم على Slack، والصفحات التي ترتفع فيها نسبة المغادرة مباشرة بعد قسم «متى تستخدمه». كل سؤال متكرّر يصبح تغييرًا في التوثيق. وإن وصل السؤال نفسه ثلاث مرات، فمكان الإجابة هو الصفحة، لا سلسلة رسائل.

في التمرين تخطّط لإصلاحات التوثيق خلف إساءة استخدام حقيقية. وبهذا يكتمل قسم المكوّنات؛ وبعده تربط جانب التصميم بجانب الكود في النظام حتى يبقيا متزامنين.