الكاتب يتحدث عن تحديات التوثيق الفني في Pinterest والسبب ورا بطء التحسن رغم جهود سابقة، وبنفس الوقت عرض إستراتيجيتهم الجديدة المبنية على docs-as-code واللي طلعت بمشروع داخلي اسمه PDocs .
📝 التحديات الأساسية:
التوثيق التقليدي في wikis كان:
نصوص غير مرتبة
جودة غير مستقرة
صعوبة في اكتشاف الحاجة للمعلومة
ده رغم محاولات مثل doc‑a‑thon وتدخل قيادات، لكن كان الفشل هو النتيجة.
💻 فلسفة Docs‑as‑Code:
التوثيق بيتم بواسطة Markdown، متوضع جنب الكود في Git.
بيعدّي بـ code review وCI/CD زي الكود الحقيقي.
بيتم تحويله لواجهة HTML باستخدام static site generator .
✅ الفوائد اللي شفناها:
تعزيز التعاون: كل تعديل بيمرّ بمراجعة زملاء، بدل التعديلات العشوائية.
تحكم في الجودة: بيحمي التوثيق من تغييرات غير مناسبة دون مراجعة .
اكتشاف أسهل: التوثيق جنب الكود وبنفس الrepository – وبينضّم لمحرك البحث الداخلي.
دقة وتحديث مستمر: أي PR للكود ممكن يشمل تحديث التوثيق، وحتى يمنع الدمج لو التوثيق ناقص .
كشف تصميم ضعيف مبكرًا: لو الصياغة مش مفهومة، ده بيكشف مشاكل في الـAPI.
تركيز على المحتوى، وسيستمك يهتم بالشكل: الـ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 موثقة ومنظمة.
النتيجة: ثقافة توثيق محسّنة أول بأول بتخدم مئات المهندسين.
المقال الاصلي هنا.