كيف تحافظون على تحديث التوثيق حين تُصدرون كل أسبوع
يراسلكم عميل: “دليلكم يقول انتقلوا إلى الإعدادات ثم التقويم. لا يوجد تقويم.” وهو محق. لقد نقلتموه إلى الحسابات قبل ستة أسابيع. روجع طلب السحب واختُبر وأُطلق. أما مقالة المساعدة فلم تتغير، لأنه لم يكن من مهمة أحد أن يغيّرها.
هكذا يحدث تقادم التوثيق في معظمه. ليس كسلًا، بل حلقة مفقودة بين “غيّرنا المنتج” و”هذه المقالات تصف الجزء الذي غيّرناه”.
للحفاظ على تحديث التوثيق حين تُصدرون كل أسبوع، اجعلوا الوثائق جزءًا من طلب السحب: كل طلب يجيب عن “هل يغيّر هذا ما يراه العميل؟”، ويسمّي مقالات المساعدة التي يمسها، ويُطلق تعديل الوثائق في الطلب نفسه أو في طلب مرتبط به. ثم أتمتوا الأجزاء الآلية (لقطات الشاشة ومدخلات سجل التغييرات) وراقبوا تذاكر الدعم وعمليات البحث في مركز المساعدة بحثًا عن الانجراف الذي يفلت.
وبقية المقال كيف تُعدّون ذلك دون توظيف كاتب تقني.
لماذا يتقادم التوثيق
لانجراف الوثائق بضعة أسباب متوقعة، ولا يُصلح أيًّا منها قولنا “لنكن أكثر حرصًا”.
الوثائق تعيش في مكان آخر. الشيفرة في GitHub. والوثائق في Intercom أو Zendesk أو Notion أو مساحة GitBook. ولا شيء يربط ملفًا في أحدهما بصفحة في الآخر، فلا يدفع تغيير في أحدهما إلى إلقاء نظرة على الآخر.
من يعرف ليس من يكتب. المهندس الذي نقل إعدادات التقويم يعرف بالضبط ما تغيّر. أما من يصون مركز المساعدة فيعرف من عميل.
الوثائق تُصلح على دفعات. “سنجري جولة للوثائق في نهاية الربع.” وفي الأثناء، ينتقص كل إصدار أسبوعي من الدقة، وإعادة الكتابة الكبرى تستغرق وقتًا طويلًا بحيث تصبح قديمة جزئيًا حين تصدر.
لا أحد يعرف أي المقالات تأثرت. حتى فريق متحمس لا يستطيع فحص 80 مقالة بعد كل إصدار. فلا يفحص أيًّا منها.
النمط هو نفسه كأي عمل صيانة آخر. التحديثات الصغيرة المستمرة تتفوق على الاندفاعات البطولية الدورية.
اجعلوا الوثائق جزءًا من تعريف الإنجاز
التغيير الأكثر فاعلية: أضيفوا قسمًا للوثائق إلى قالب طلب السحب لديكم. وسيملؤه GitHub مسبقًا في كل طلب إذا وضعتم ملفًا في .github/pull_request_template.md (دليل GitHub لقوالب طلبات السحب).
## Docs impact
- [ ] This changes something a customer can see or do
- Help articles affected: <!-- slugs or links, or "none" -->
- [ ] Screenshots need re-capturing
- [ ] Changelog entry drafted (or marked "internal only")
يبدو بيروقراطية لنحو أسبوعين. ثم يصبح اللحظة التي يقول فيها المهندس “آه، مقالة الاستقبال تذكر هذه الشاشة” بينما السياق ما زال طازجًا. وإصلاح وثائق من سطرين يكتبه من أجرى التغيير أفضل من إصلاح مثالي يُكتب بعد شهر من التخمين.
وقاعدتان تجعلان ذلك يثبت:
- المراجعون يتحققون من الخانة. إذا كان طلب سحب يغيّر الواجهة بوضوح ويقول “لا أثر على الوثائق”، فيسأل المراجع لماذا. تمامًا كما في غياب الاختبار.
- تعديل الوثائق يمكن أن يكون خشنًا. لا يحتاج المهندسون إلى كتابة نثر مصقول. “الخطوة 6 الآن: افتحوا الحسابات، ثم إعدادات التوفر” تكفي. ويستطيع أحدهم تحسين الصياغة لاحقًا. الدقة أولًا.
اربطوا مقالات المساعدة بالشيفرة التي تصفها
تعتمد قائمة تحقق طلب السحب على أن يتذكر الناس أي المقالات موجودة. ساعدوهم بخريطة بسيطة من مسارات الشيفرة إلى المقالات:
# docs-map.yml
- paths: ["src/features/calendar/**", "src/pages/accounts/availability*"]
articles: ["connect-your-calendar", "set-your-availability"]
- paths: ["src/features/billing/**"]
articles: ["change-your-plan", "update-payment-method", "download-invoices"]
- paths: ["src/features/onboarding/**"]
articles: ["get-started"]
ثم تقرأ خطوة CI صغيرة قائمة الملفات المتغيرة (git diff --name-only origin/main...HEAD)، وتطابقها مع الأنماط، وتنشر تعليقًا على طلب السحب: “يمس هذا الطلب شيفرة التقويم. افحصوا: connect-your-calendar وset-your-availability.” وهذا نحو 40 سطرًا من النص البرمجي، ويحوّل “فكروا في الوثائق” إلى قائمة محددة قابلة للنقر.
والخريطة تتقادم أيضًا بالطبع. احتفظوا بها بجانب الشيفرة، وأضيفوا سطرًا كلما كتب أحدهم مقالة جديدة. ومع ذلك فصيانتها أسهل بكثير من صيانة الوثائق نفسها.
وإذا كانت وثائقكم في المستودع نفسه (التوثيق كشيفرة باستخدام أدوات مثل Docusaurus أو Mintlify أو مزامنة Git في GitBook)، فيمكنكم الذهاب أبعد: مدخل CODEOWNERS على مجلد الوثائق يضمن أن شخصًا يهتم بالوثائق يراجع كل تغيير فيها.
اكتبوا وثائق تتعفن ببطء أكبر
بعض خيارات الكتابة تجعل صيانة التوثيق أسهل بكثير:
- صفوا المهام لا التخطيطات. “افتحوا الحسابات واختاروا إعدادات التوفر” تصمد أمام إعادة التصميم. أما “انقروا على الزر الأرجواني في أعلى اليمين” فلا تصمد.
- استخدموا تسميات الواجهة بالضبط بخط عريض. حين تتغير تسمية، يجد البحث عن التسمية القديمة كل مقالة تحتاج إلى إصلاح.
- لا تكرروا الوقائع المتقلبة. حدود الباقات والأسعار ومدد التجربة تتغير. ضعوها في صفحة واحدة وأحيلوا إليها بدل إعادة ذكرها في عشر مقالات.
- صوّروا الجزء الثابت. اقتصّوا على العنصر الذي تتناوله الخطوة بدل الشاشة كلها، حتى لا يُبطل تغيير في الشريط الجانبي كل صورة.
- اعرضوا تاريخ “آخر تحديث”. فهو يبقيكم صادقين، ويخبر القراء بمقدار ما ينبغي أن يثقوا بالصفحة.
مزيد من التفاصيل عن البنية في دليلنا عن كتابة مقالات مركز المساعدة التي يستخدمها الناس فعلًا.
أتمتوا الأجزاء الآلية
بعض صيانة الوثائق حكم. وكثير منها مجرد أعمال روتينية يؤديها النص البرمجي أفضل.
لقطات الشاشة. إعادة التقاط الصور يدويًا أول ما ينبغي أتمتته. فنص Playwright على حساب تجريبي مهيأ ببيانات جاهزة، يُشغَّل في CI، يعطيكم صورًا جديدة متسقة عند كل دمج. ونستعرض النص كاملًا في كيف تنشئون لقطات شاشة للمنتج تلقائيًا.
مدخلات سجل التغييرات. طلبات السحب المدمجة لديكم تصف أصلًا ما أُطلق. وتحويلها إلى سجل تغييرات موجه للعملاء هو في معظمه إعادة كتابة لغة المهندسين بلغة بسيطة وتجميعها بحسب Added وChanged وFixed، وهو العرف الذي عمّمه Keep a Changelog. راجعوا كيف تكتبون سجل تغييرات يقرؤه العملاء للاطلاع على القوالب.
الفيديوهات. إذا كانت لديكم فيديوهات إرشادية، فإن خريطة مسارات الشيفرة نفسها تخبركم أيها يحتاج إلى إعادة تسجيل. وتسجيل الصورة والصوت منفصلين يجعل الإعادة سريعة؛ هذه هي العملية لفيديوهات المنتج الإرشادية.
اكتشفوا الانجراف الذي لديكم بالفعل
حتى مع عملية جيدة، تفلت بعض التغييرات. وهذه الإشارات تخبركم أين:
- تذاكر الدعم التي تقتبس وثائقكم. “الدليل يقول X لكنني أرى Y” بلاغ خطأ مجاني. ضعوا عليها وسمًا وأصلحوا المقالة في اليوم نفسه.
- عمليات بحث في مركز المساعدة بلا نتائج. أناس يبحثون عن اسم ميزة غيّرتم اسمها، أو ميزة لم توثقوها قط.
- ملاحظات القراء على المقالات. إذا كان في مركز مساعدتكم “هل كان هذا مفيدًا؟”، فاقرؤوا تعليقات الإبهام للأسفل أسبوعيًا. وهي عادةً محددة.
- جولة قصيرة على أهم صفحاتكم. مرة كل شهر، تنقلوا بين أكثر 20 مقالة مشاهدة في المنتج الحقيقي. تستغرق نحو ساعة وتغطي معظم ما يقرؤه العملاء فعلًا.
لا توثّقوا ما لم يُطلق بعد
فخ تقع فيه الفرق سريعة الحركة: يُدمج طلب سحب خلف علم ميزة (feature flag)، ويحدّث أحدهم الوثائق بإخلاص، وإذا بمركز المساعدة يصف ميزة لا يراها معظم العملاء. فيرتبك العملاء، ويتلقى الدعم التذاكر.
احتفظوا بتغييرات الوثائق الخاصة بالعمل المحجوب بعلم ميزة حتى يُفعَّل العلم للجميع (أو اكتبوها كمسودات وانشروها مع الطرح). والأمر نفسه ينطبق على مدخلات سجل التغييرات.
أدوات تساعد في صيانة التوثيق
مكاتب المساعدة مثل Intercom وZendesk وHelp Scout لديها محررات مراكز مساعدة جيدة تمامًا، لكنها لا تعرف شيئًا عما في شيفرتكم، فكل الربط أعلاه عليكم. ومنصات التوثيق كشيفرة مثل GitBook وMintlify تحتفظ بالوثائق في Git، فتحصلون على مراجعة طلبات السحب والتاريخ، وتعمل على أفضل وجه حين يكون كتّابكم مرتاحين داخل المستودع. وأدوات مراكز المساعدة الأحدث التي تضع الذكاء الاصطناعي أولًا، ومنها Ferndesk، تحاول سد الفجوة من زوايا أخرى.
وقد بنينا Ellie Docs خصيصًا حول الصلة بطلب السحب. تربطون مستودع GitHub، وترسم Ellie خريطة لميزاتكم وتربط كل مقالة مساعدة بالميزات التي تصفها. وعند كل طلب سحب مدموج، تفحص المقالات التي يؤثر فيها التغيير وتقترح تعديلات على هيئة فروقات قابلة للمراجعة، مع شرح موجز للسبب. تقبلون كل اقتراح أو ترفضونه. لا شيء يُنشر من تلقاء نفسه.

وهي تصوغ أيضًا مدخلات سجل التغييرات من طلبات السحب المدمجة نفسها، وتحجب كل ما ما زال خلف علم ميزة حتى يُطلق.

يمكنكم فعل كل ما في هذا المقال يدويًا، وفرق كثيرة تفعل. وEllie فقط تؤدي لكم جزء “أي المقالات يؤثر فيها هذا الطلب، وما الذي ينبغي أن يتغير؟” في كل مرة.
أسئلة شائعة
من ينبغي أن يملك التوثيق في فريق صغير؟ شخص واحد مسمّى يملك مركز المساعدة ككل (غالبًا المؤسس أو من يتولى الدعم)، لكن كل مهندس يملك أثر طلبات السحب الخاصة به على الوثائق. فالملكية المشتركة دون مالك مسمّى تعني غياب المالك.
كم مرة ينبغي أن نراجع وثائقنا؟ باستمرار للتغييرات (عبر قائمة تحقق طلب السحب)، إضافة إلى جولة شهرية على أكثر مقالاتكم مشاهدة. وإعادة الكتابة الفصلية الكبرى علامة على أن الجزء المستمر لا يحدث.
هل يستحق التوثيق كشيفرة العناء لوثائق مساعدة العملاء؟ إذا كان من يكتبون مهندسين، نعم. وإذا كان الدعم أو التسويق يكتب معظمها، فمحرر مركز مساعدة عادي مع قائمة تحقق طلبات السحب وخريطة وثائق يعمل عادةً أفضل من إجبار الجميع على Git.
ما أسرع مكسب إذا كانت وثائقنا قديمة جدًا أصلًا؟ أصلحوا أكثر 10 مقالات زيارةً، وأضيفوا قالب طلب السحب، وابدؤوا بوسم تذاكر الدعم التي تذكر الوثائق. هذا يوقف النزيف قبل أن تتعاملوا مع الذيل الطويل.
وإذا فضلتم أن تُقترح عليكم تحديثات الوثائق عند كل طلب سحب، فـجرّبوا Ellie Docs مجانًا. اربطوا مستودعًا، واحصلوا على مركز مساعدة مصوغ، وراجعوا التعديلات المقترحة وأنتم تُطلقون.