انتقل إلى المحتوى
جديدقوالب وأدوات رقمية قيد الإطلاق — انضم لقائمة الانتظار
Hecham Gazhi

أنظمة التصميم · الدرس 11 / 13

التوثيق

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

4 دقائق قراءة · 5 أسئلة

لماذا يصنع التوثيق النظام أو يهدمه

المكوّن دون توثيق تخمين. سيستخدمه الناس في الأماكن الخطأ، أو يجمعونه بطرق غريبة، أو يعيدون بناءه لأنهم لم يعرفوا بوجوده. التوثيق يحوّل مكتبة الأجزاء إلى لغة مشتركة ومجموعة قرارات يتبعها الجميع.

التوثيق الجيد يجيب عن الأسئلة قبل طرحها — فلا يضطر فريق نظام التصميم للإجابة عن رسالة Slack نفسها عشرين مرة في الأسبوع.

اعرف جماهيرك

الجمهورما يحتاجه
المصممونمتى يُستخدم ماذا، وأمثلة بصرية، وما يجب فعله وتجنبه، واستخدام Figma
المطورونتعليمات التثبيت، وأمثلة الكود، والخصائص/الواجهة البرمجية، وسلوك إمكانية الوصول
مديرو المنتجاتما الموجود، وما المخطط، وكيف يطلبون شيئًا
كتّاب المحتوىالصوت والنبرة، والمصطلحات، وكيف تُكتب التسميات والأخطاء
أعضاء الفريق الجددالبدء، والمبادئ، وأين يجدون المساعدة

بنية موقع التوثيق

  • البدء — للمصممين وللمطورين.
  • المبادئ — مبادئ تصميم النظام.
  • الأسس — الألوان، والطباعة، والمسافات، والتخطيط، والارتفاع، والحركة، والأيقونات — مع الرموز.
  • المكوّنات — صفحة لكل منها.
  • الأنماط — النماذج، والحالات الفارغة، والأخطاء، والتنقل…
  • المحتوى — الصوت والنبرة، والقواعد، والمصطلحات.
  • الموارد — روابط مكتبة Figma، وحزم الكود، والقوالب.
  • المساهمة وخارطة الطريق وسجل التغييرات — كيف يتطور النظام.
  • البحث — ضروري بمجرد وجود أكثر من بضع صفحات.

قالب صفحة المكوّن

استخدام البنية نفسها في كل صفحة مكوّن يجعل التوثيق قابلًا للتوقع وسهل المسح:

  1. 1الاسم ووصف من سطر واحد — ما هو وما غرضه الأساسي.
  2. 2مثال حي — تفاعلي، بمحتوى حقيقي.
  3. 3متى يُستخدم / متى لا يُستخدم — وما البديل.
  4. 4التشريح — مخطط مرقّم للأجزاء.
  5. 5المتغيرات والأحجام والحالات — لكل منها شرح قصير.
  6. 6السلوك — التفاعلات، والسلوك المتجاوب، وحدود المحتوى (الالتفاف، القص).
  7. 7إرشادات المحتوى — كيف تُكتب التسميات والرسائل لهذا المكوّن.
  8. 8ما يجب فعله وتجنبه — أمثلة بصرية متقابلة.
  9. 9إمكانية الوصول — سلوك لوحة المفاتيح، والتركيز، وARIA، وما يجب أن تقدمه فرق المنتج.
  10. 10الكود — الاستيراد، ومثال الاستخدام، وجدول الخصائص.
  11. 11المكوّنات والأنماط ذات الصلة.
  12. 12الحالة وسجل التغييرات — مثل مستقر، تجريبي، مهمل.
مثالtext
Button
Buttons let people take actions with a single click or tap.

When to use
✓ To submit a form, start a task, or confirm a decision.
✗ To navigate to another page — use a Link instead.

Props
| Prop     | Type                                  | Default   |
|----------|---------------------------------------|-----------|
| variant  | "primary" | "secondary" | "danger"   | "primary" |
| size     | "sm" | "md" | "lg"                   | "md"      |
| loading  | boolean                               | false     |

إرشادات كتابة التوثيق

افعل

  • اكتب للمسح السريع: عناوين قصيرة، وفقرات قصيرة، وقوائم.
  • ابدأ بأهم إرشاد.
  • استخدم محتوى حقيقيًا في الأمثلة، لا Lorem ipsum.
  • اشرح السبب وراء القواعد حتى يطبّقها الناس على حالات جديدة.
  • استخدم مصطلحات متسقة — الأسماء نفسها كما في Figma والكود.

لا تفعل

  • تكتب مقالات طويلة لا يقرؤها أحد.
  • تعرض الأمثلة المثالية فقط — اعرض الحالات الطرفية والحدود.
  • تستخدم مصطلحات داخلية دون شرح.
  • تدع التوثيق يتقادم — التوثيق الخاطئ أسوأ من عدمه.
  • تخفي التوثيق في أماكن كثيرة (بعضه في Notion، وبعضه في Figma، وبعضه في ويكي).

معايير المحتوى

تتضمن أنظمة تصميم كثيرة إرشادات للكلمات في الواجهة، لأن اللغة غير المتسقة مربكة مثل المرئيات غير المتسقة:

  • الصوت والنبرة — مثل: واضح، ودود، واثق؛ وأكثر جدية في الأخطاء ومسارات الدفع.
  • أسلوب الكتابة — صيغ موحدة للأزرار والعناوين تسهل القراءة.
  • المصطلحات — قائمة كلمات: "تسجيل الدخول" لا "الولوج"؛ و"حذف" مقابل "إزالة" (الحذف = اختفى نهائيًا، والإزالة = أُخرج من مجموعة).
  • الصيغ — التواريخ والأوقات والأرقام والعملات وأرقام الهواتف لكل لغة ومنطقة.
  • أنماط الرسائل — قوالب للخطأ والنجاح والحالة الفارغة والتأكيد.
  • اللغة الشاملة — تجنّب التعابير المحلية والمصطلحات المنحازة للجنس واللغة المسيئة لذوي الإعاقة.

أدوات التوثيق

الأداةالاستخدام المعتاد
Storybookأمثلة تفاعلية لمكوّنات الكود وخصائصها؛ وغالبًا الجانب البرمجي من التوثيق
Zeroheight وSupernova وKnapsackمواقع توثيق أنظمة التصميم التي تربط Figma بالكود
موقع مخصص (مثل Next.js وDocusaurus)تحكم كامل؛ ومكوّنات حية؛ ومناسب للأنظمة العامة
Notion / Confluenceبداية سريعة للفرق الصغيرة؛ وأصعب في التزامن مع المكوّنات
Figmaأوصاف المكوّنات وصفحات مشروحة داخل المكتبة

أفضل أداة هي التي سيحافظ فريقك على تحديثها. ربط التوثيق من وصف مكوّن Figma ومن تعليقات مكوّن الكود يضع الإرشاد حيث يوجد الناس أصلًا.

هل التوثيق ناجح؟

  • تتبّع الأسئلة التي يطرحها الناس على فريق النظام — الأسئلة المتكررة تشير إلى توثيق ناقص.
  • انظر إلى عبارات البحث التي لا تعطي نتائج.
  • افحص تحليلات الصفحات للصفحات الأكثر والأقل مشاهدة.
  • راقب سوء الاستخدام في المنتجات — مكوّن يُستخدم خلافًا للإرشاد يعني أن الإرشاد غير واضح أو لا يُعثر عليه.
  • أجرِ اختبارات قابلية استخدام قصيرة للتوثيق مع أعضاء الفريق الجدد.

أهم النقاط

  • يحوّل التوثيق المكوّنات إلى قرارات مشتركة ويقلل الأسئلة المتكررة.
  • اكتب لجماهير مختلفة: المصممون، والمطورون، ومديرو المنتجات، والكتّاب، والقادمون الجدد.
  • استخدم قالبًا واحدًا متسقًا لكل صفحة مكوّن، بما في ذلك متى لا يُستخدم وإمكانية الوصول.
  • ضمّن معايير المحتوى: الصوت، وأسلوب الكتابة، والمصطلحات، وأنماط الرسائل.
  • قِس فائدة التوثيق عبر الأسئلة والبحث والتحليلات وسوء الاستخدام — وحافظ على تحديثه.

تمرين

اكتب صفحة مكوّن

  1. اختر مكوّنًا صممته سابقًا (مثل حقل نص).
  2. اكتب الصفحة باستخدام القالب ذي الاثني عشر جزءًا.
  3. أنشئ زوجين من أمثلة ما يجب فعله وتجنبه.
  4. اكتب قسم إمكانية الوصول مع سلوك لوحة المفاتيح.
  5. اطلب من زميل استخدام صفحتك فقط لتصميم نموذج، ودوّن ما يسألك عنه.

اختبر نفسك

اختبار: التوثيق

5 أسئلة. احصل على 70٪ أو أكثر لإكمال الدرس.

  1. 1.أي قسم يساعد الناس على تجنب سوء استخدام المكوّن؟
  2. 2.لماذا نستخدم محتوى حقيقيًا في أمثلة التوثيق؟
  3. 3.فيمَ يُستخدم Storybook عادة في أنظمة التصميم؟
  4. 4.لماذا نضمّن المصطلحات في معايير المحتوى؟
  5. 5.الأسئلة المتكررة لفريق نظام التصميم تعني عادة…