كيف قام فريق التوثيق بإصلاح الصفحات الصحيحة من خلال السؤال في الصفحة نفسها

يتمتع مشروع مفتوح المصدر بتوثيق جيد ومشكلة حقيقية: دليل التثبيت خاطئ بشكل غير ملحوظ. لقد تغيرت إحدى الخطوات منذ إصدارين، والآن يعلق الوافدون الجدد في نفس النقطة. يلاحظ الناس ذلك — هناك تذمر على وسائل التواصل الاجتماعي وسؤالان مرتبكان في دردشة المجتمع — لكن لا يستطيع المشرفون التصرف حيال أي من ذلك، لأن أياً من الشكاوى لا يحدد **أي صفحة**. "توثيقك قديم" هو شعور، وليس تقرير عن خطأ. لذلك تبقى الخطوة الخاطئة هناك لأشهر، وتبعد بهدوء كل مستخدم جديد يحاول البدء. يعيش التوثيق أو يموت بناءً على هذه الحلقة: يواجه القارئ فقرة محيرة أو خاطئة، ويخبر المشرفين بمكانها بالضبط، ثم يقوم المشرفون بإصلاحها. إذا كسرت "بمكانها بالضبط"، فإن الحلقة بأكملها ستتوقف. ## المشكلة: الملاحظات بدون موقع هي مجرد ضوضاء القراء مستعدون للمساعدة. سيخبرونك بكل سرور أن الصفحة مربكة. لكن ما لن يفعلوه هو عملية التنقيب المطلوبة لجعل هذه المساعدة قابلة للتنفيذ — نسخ الـ URL، العثور على قناة الاتصال الصحيحة، وصف المشكلة، وملاحظة أي قسم وأي إصدار. إنها خطوات كثيرة بالنسبة لشخص يحاول تعلم أداتك، وليس تدقيق توثيقك. لذا فإن الملاحظات التي تصل تكون مجردة من الشيء الوحيد الذي يجعلها مفيدة: الموقع. المشرف الذي يقرأ "توثيق واجهة برمجة التطبيقات (API) خاطئ" لديه مئات الصفحات وليس لديه فكرة عن مكان البحث. تساعد مشكلة GitHub، لكنها تطلب من القارئ العابر أن يكون لديه حساب، وأن يفهم قالب المشكلة الخاص بك، وأن يغير السياق خارج التوثيق تمامًا — وهو احتكاك يصفي معظم الملاحظات العابرة، وهي بالضبط الملاحظات التي تلتقط أخطاء صغيرة وعالية التأثير. النتيجة هي اختلال غريب: الكثير من القراء يلاحظون مشاكل، لكن لا يتم الإبلاغ عن أي منها تقريباً في شكل يمكنك إصلاحه. ## الحل: رابط "الإبلاغ عن مشكلة" في كل صفحة ضع رابطًا صغيرًا **الإبلاغ عن مشكلة في هذه الصفحة** في تذييل كل صفحة توثيق. إنه رابط `mailto:`، وحيلته هي أنه يملأ مسار الصفحة الحالي مسبقًا في الموضوع والمحتوى. ينقر القارئ، ويُفتح بريده الإلكتروني مع التقاط الموقع بالفعل، وكل ما يضيفه هو ما كان خاطئًا. نظراً لأن التوثيق يُبنى عادةً من قالب أو منشئ مواقع ثابتة، يمكنك حقن المسار تلقائيًا. في موقع قائم على قوالب، ضع متغير الصفحة مباشرة في الرابط: ```html <a href="mailto:docs@yourproject.dev?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> الإبلاغ عن مشكلة في هذه الصفحة </a> ``` أو قم بتعيينه باستخدام سطر من نص برمجي (script) ليعمل على أي صفحة بدون قوالب: ```html <a id="docs-issue" href="#">الإبلاغ عن مشكلة في هذه الصفحة</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:docs@yourproject.dev' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` المنشئ على هذا الموقع ينتج الرابط المشفر؛ يقوم البرنامج النصي فقط بتبديل المسار المباشر. الآن كل تقرير يسمي الصفحة الدقيقة في موضوعه، ويمكن للمشرف الانتقال مباشرة إلى الملف المصدر. ## لماذا تتفوق الصفحة نفسها على متتبع المشاكل هنا يعد متتبع المشاكل هو المكان المناسب للإصلاح، ولكنه باب أمامي ضعيف للملاحظات. فهو يتطلب حسابًا، وتغييرًا في السياق، وإلمامًا بعمليتك — وهي حواجز تبعد القارئ العابر الذي اكتشف للتو خطأ مطبعي في نموذج كود. يقابل رابط `mailto:` القراء في المكان الذي يحدث فيه الارتباك فعليًا: على الصفحة، بنقرة واحدة، وبدون حساب. إنه يلتقط الذيل الطويل من التصحيحات الصغيرة التي لن تنجو أبدًا من الرحلة إلى المتتبع. يعمل الاثنان معًا بشكل جيد. تصل التقارير عبر البريد الإلكتروني، موسومة مسبقًا بالصفحة؛ يقوم المشرف بفرزها ويفتح مشاكل في المتتبع فقط لتلك التي تستحق التتبع. تحصل على احتكاك منخفض للبريد الإلكتروني في المقدمة وصرامة المتتبع في الخلفية. ## الإعداد 1. اختر صندوق وارد للتوثيق مثل `docs@` يراقبه المشرفون. 2. في المنشئ، حدد المستلم، وموضوع 'Docs issue: [مسار الصفحة]'، ومحتوى يطلب معرفة ما هو الخطأ وما الذي يمكن أن يساعد. 3. أضف الرابط إلى تذييل قالب صفحتك، مع حقن المسار باستخدام متغير الصفحة الخاص بمنشئك أو البرنامج النصي الصغير أعلاه. 4. قم بتوجيه البريد الوارد حسب علامة الموضوع 'Docs issue:' حتى تهبط التقارير في مكان واحد. 5. أغلق الحلقة: عندما تقوم بإصلاح صفحة تم الإبلاغ عنها، فإن ردًا من سطر واحد للقارئ يحول تقرير الخطأ إلى حسن نية. ## ما الذي يوفره التوفير الأول هو **وقت المشرف المستغرق في تحديد موقع المشاكل**. عندما يسمي كل تقرير الصفحة، فإنك تتخطى العمل البوليسي وتتجه مباشرة إلى الإصلاح. التقرير الذي كان عبارة عن "هناك خطأ ما في مكان ما" غير قابل للتنفيذ يصبح تعديلاً يستغرق دقيقتين. التوفير الثاني هو **عدد أقل من المستخدمين العالقين**. أخطاء التوثيق تتراكم: خطوة التثبيت الخاطئة لا تفشل مرة واحدة، بل تفشل لكل وافد جديد حتى يقوم شخص ما بإصلاحها. تقصير الوقت من "يلاحظ القارئ" إلى "المشرف يعرف مكان الخطأ بالضبط" يعني أن كل فقرة سيئة تبعد عددًا أقل بكثير من الأشخاص. بالنسبة لأداة تنمو بالاعتماد، فإن إزالة العقبات أمام الوافدين الجدد هو نمو. التوفير الثالث هو **حجم وصدق الملاحظات**. لأن الإبلاغ يتطلب نقرة واحدة وبدون حساب، فإن المزيد من القراء يقومون بذلك — بما في ذلك أولئك الذين لن يفتحوا أبدًا مشكلة في المتتبع. تسمع عن الأخطاء الصغيرة والمحرجة التي تقوض الثقة، وتسمع عنها بينما لا تزال مهمة. ## كيف تجعله أفضل - قم بالملء التلقائي **لإصدار التوثيق أو الـ commit** بجانب المسار، لتتمكن من معرفة ما إذا كان التقرير يسبق إعادة كتابة حديثة. - أضف الرابط إلى **صفحات 404** في توثيقك، حيث تكون الصفحة المفقودة بحد ذاتها إشارة مفيدة. - حافظ على العنوان **مخفياً** حتى لا تلتقطه البوتات من آلاف الصفحات العامة. - قدم بديلاً مرئيًا للقراء الذين ليس لديهم تطبيق بريد إلكتروني افتراضي، مثل عنوان نصي عادي أو رابط إلى متتبع. ## النقاط الرئيسية - ملاحظات التوثيق بدون موقع هي مجرد ضوضاء؛ نادراً ما يقوم القراء بالعمل لإرفاق موقع. - رابط `mailto:` لـ "الإبلاغ عن مشكلة" في كل صفحة يملأ المسار الدقيق مسبقاً، لذلك كل تقرير يكون قابلاً للتنفيذ. - يلتقط البريد الإلكتروني الموجود على الصفحة التصحيحات العابرة التي يصفيها المتتبع، ثم يغذي المتتبع للإصلاحات الحقيقية. - يوفر وقت المشرف، ويزيل العقبات أمام الوافدين الجدد بشكل أسرع، ويبرز الأخطاء الصغيرة التي تكلف الثقة بصمت. قم ببناء رابط ملاحظات التوثيق الخاص بك في [المنشئ](/#generator)، أو انسخ الإعداد أدناه.