إزاي Pinterest حولوا التوثيق لأكوادهم

حسّن الجودة، الاكتشافية، والتنظيم Docs‑as‑Code استخدام منهج

الكاتب يتحدث عن تحديات التوثيق الفني في Pinterest والسبب ورا بطء التحسن رغم جهود سابقة، وبنفس الوقت عرض إستراتيجيتهم الجديدة المبنية على docs-as-code واللي طلعت بمشروع داخلي اسمه PDocs .

📝 التحديات الأساسية:

• التوثيق التقليدي في wikis كان:

  • نصوص غير مرتبة

  • جودة غير مستقرة

  • صعوبة في اكتشاف الحاجة للمعلومة

ده رغم محاولات مثل doc‑a‑thon وتدخل قيادات، لكن كان الفشل هو النتيجة.

💻 فلسفة Docs‑as‑Code:

• التوثيق بيتم بواسطة Markdown، متوضع جنب الكود في Git.

• بيعدّي بـ code review وCI/CD زي الكود الحقيقي.

• بيتم تحويله لواجهة HTML باستخدام static site generator .

✅ الفوائد اللي شفناها:

1. تعزيز التعاون: كل تعديل بيمرّ بمراجعة زملاء، بدل التعديلات العشوائية.

2. تحكم في الجودة: بيحمي التوثيق من تغييرات غير مناسبة دون مراجعة .

3. اكتشاف أسهل: التوثيق جنب الكود وبنفس الrepository – وبينضّم لمحرك البحث الداخلي.

4. دقة وتحديث مستمر: أي PR للكود ممكن يشمل تحديث التوثيق، وحتى يمنع الدمج لو التوثيق ناقص .

5. كشف تصميم ضعيف مبكرًا: لو الصياغة مش مفهومة، ده بيكشف مشاكل في الـAPI.

6. تركيز على المحتوى، وسيستمك يهتم بالشكل: الـstatic site generator بيقدّم مظهر موحد للdocs، من غير مشاكل WYSIWYG .

🛠️ بناء PDocs:

• Pinterest ما لاقتش أداة جاهزة بتدعم docs‑as‑code على مستوى الشركة.

• فبنوا PDocs، اللي بتمشي على Next.js وUnified ecosystem، وقادر يمسح مستودعات مختلفة ويجمّعهم في site واحد .

• بيستخدم ملفات إعداد صغيرة (pdocs.yaml) زي MkDocs.

• بيدعم live preview أثناء التعديل والـwatchers للتحديث الفوري.

📚 واجهة PDocs:

• واجهة منظمة على حسب المشروع، مش صفحات مبعثرة.

• بتخلي الاكتشاف والتصفح أسهل، وبتمد الحلول التقنية بنظام documentation مرتب وصحي.

---

🔍 الخلاصة:

Pinterest خطوا خطوة لمّا دمجوا التوثيق في سير عمل الكود نفسه، وحوّلوا docs من overhead لفائدة حقيقية:

• التعاون، الجودة، الاكتشاف، والتحديث كلهم أصبحوا جزء من flow المعتاد.

• PDocs عنصر داخلي قوي لمسار واحد من الكود لdoc موثقة ومنظمة.

• النتيجة: ثقافة توثيق محسّنة أول بأول بتخدم مئات المهندسين.

المقال الاصلي هنا.