التوثيق باعتباره منتجًا

Spec: ISO/IEC/IEEE 26514 Spec: ISO/IEC/IEEE 26513 Spec: ISO 24495-1 Evidence: Standard-backed

لمحة سريعة

تُبنى هذه الصفحات وفق نموذج لجودة التوثيق، وتُكتب تحت خط أساس من اللغة الواضحة وتسلسل هرمي متعدد الطبقات للأسلوب، وتُفحص بالنوع نفسه من البوابات الآلية التي تعمل على شيفرة المحرك. تشرح هذه الصفحة ذلك الانضباط، وسبب تسجيل ⁨NextPDF⁩ أيَّ خلل في التوثيق بوصفه خللًا هندسيًا.

إنها مكتوبة لمهندس كبير اكتوى بمستندات واثقة لا يمكن التحقق منها، ويريد أن يعرف ما الذي يجعل هذه المستندات مختلفة قبل أن يثق بها.

لماذا يهم هذا

تُشترى مكتبة المستندات بناءً على الثقة، والتوثيق هو الموضع الذي تُمنح فيه تلك الثقة أو تُسحب. الصفحة الخاطئة على نحو لا يمكنك اكتشافه أسوأ من عدم وجود صفحة أصلًا؛ فهي تحوِّل حذرك إلى ثقة في غير محلها. ثم يظهر الإخفاق في بيئة الإنتاج واسمك مدوَّن على الـ ⁨commit.⁩

أدبيات المعايير صريحة بشأن ما هو على المحك. فمعلومات المستخدِم المصمَّمة جيدًا تفعل أكثر من خفض تكلفة الدعم؛ إذ تعزِّز سمعة المنتج والجهة المنتِجة له. وتكتسب تلك القيمة بإدخال اختبارات التحقُّق والمصادقة ضمن التطوير، لا بعده Spec: ISO/IEC/IEEE 26513, §Foreword . يأخذ NextPDF ذلك على نحو حرفي: التوثيق سطح من أسطح المنتج له معيار للجودة، لا مجاملة مرفقة بالشيفرة.

النسخة المختصرة

يُخضع NextPDF هذه المستندات إلى نموذج صريح لجودة المعلومات مشتق من معايير معلومات المستخدِم في §8: يجب أن تكون الصفحة دقيقة تقنيًا، وأن تستخدم مفردات متّسقة واحدة، وأن تكون مفهومة لقارئها المُعلَن، وأن تقول ما يلزم فقط من دون إغفال أي شيء مطلوب، وأن تظل في متناول التقنيات المساعِدة Spec: ISO/IEC/IEEE 26514, §8 .
البنية ليست مرتجَلة. الموضوعات منظَّمة في تسلسل هرمي مجمَّد مع بيانات وصفية (القسم، والجمهور، ومستوى الدليل) كي يعثر القارئ على الموضوع بالتعرّف Spec: ISO/IEC/IEEE 26514, §9 ، وتقع أهمّ عبارة قرب أعلى كل صفحة Spec: ISO 24495-1, §5 .
يحكُم الصوتَ تسلسل هرمي معتمَد للأسلوب — ⁨Apple⁩ للنبرة، و⁨Microsoft⁩ للإجراءات، و⁨Google⁩ للشيفرة، واللغة الواضحة في كل ذلك — مسجَّل داخل المستودع مع البند المصدري الذي يتجاوزه كل اختلاف.
الجودة مُتحقَّق منها آليًا. يفرض ⁨Vale⁩ حِزَم الصوت؛ ومجموعة من بوابات composer docs:* تفرض سلامة الروابط، ونظافة الاستشهادات، وعدم وجود نص حرفي من المعايير، وعدم تسرُّب أي تفصيل خاص.
تُطوَّر المستندات مع الشيفرة، تكراريًا — يشحن كل تغيير توثيقه الخاص، لا تراكمًا لاحقًا منه Spec: ISO/IEC/IEEE 26515, §Introduction .

كيف يتعامل ⁨NextPDF⁩ مع ذلك

نموذج للجودة، مكتوب صراحةً

“المستندات الجيدة” تعبير لا يمكن دحضه ما لم تُسمَّ السمات صراحةً. يعيد NextPDF صياغة معايير معلومات المستخدِم في §8 بتعبيراته الخاصة بوصفها المعيار الذي تُقاس به كل صفحة Insider_‎: يجب أن تكون كل صفحة دقيقة تقنيًا، وأن تلتزم بمفردات متّسقة واحدة، وأن تكون مفهومة لقارئها المُعلَن، وأن تحمل ما يحتاجه ذلك القارئ فقط من دون إغفال أي شيء مطلوب، وأن تظل في متناول التقنيات المساعِدة Spec: ISO/IEC/IEEE 26514, §8 . هذه ليست صفات؛ بل معايير مراجعة. اختبار “ما يلزم لكن مكتمل” هو السبب في أن الصفحة تذكر حدّها وتتوقف، بدلًا من الحشو. اتساق المفردات هو السبب في أن المصطلحات محكومة (أدناه). وإمكانية الوصول هي السبب في أن كل مكوِّن آمن مع لوحة المفاتيح وقارئ الشاشة، ولا يشير أبدًا باللون وحده.

بنية بالتحليل، لا بالذوق

تُجمَّد تصنيفات Insider_‎ قبل كتابة أي صفحة، وهذا مقصود. يشترط ISO 26514 أن يكون تحليل الجمهور والمهام سابقًا لتصميم المعلومات Spec: ISO/IEC/IEEE 26514, §9 . كما يشترط تنظيم الموضوعات في تسلسلات هرمية أو مجموعات، يحمل كل منها بيانات وصفية تحدِّد جمهورها ونوع معلوماتها، كي يحدِّد المستخدمون ما يحتاجونه بسرعة Spec: ISO/IEC/IEEE 26514, §9 . في هذا المستودع تكون تلك البيانات الوصفية front-matter ملموسة — section، وaudience، وevidence_level، وtags — وخريطة العناقيد ملف واحد مجمَّد. يختار القارئ الصفحة بالتعرّف؛ ولا يضطر أحد إلى استرجاع معرّف من ذاكرته.

داخل الصفحة، يكون الترتيب ثابتًا وواحدًا في كل مكان، وتوضع أكثر العبارات فائدةً حيث يجدها القارئ أولًا — وهو غالبًا البداية Spec: ISO 24495-1, §5 . لهذا السبب تضع كل صفحة Insider_‎ النسخة المختصرة قبل التفصيل: يستطيع القارئ التوقف بعد ثلاثة أقسام، ومع ذلك يخرج بإجابة يمكن الدفاع عنها.

تسلسل هرمي للأسلوب مدعوم بالإثباتات

لا يُترك الصوت لمزاج الكاتب. يحمل المستودع ورقة تجاوزات معتمَدة (docs/style/nextpdf-overrides.md) تضع ⁨Apple⁩ (النبرة)، و⁨Microsoft MSTP⁩ (الإجراءات ومصطلحات واجهة المستخدم)، و⁨Google DDSG⁩ (الشيفرة وواجهة سطر الأوامر) فوق خطوط أساس اللغة الواضحة والمفردات المضبوطة، مع جدول لحل التعارض لكل وضع. أما قاعدتها الأشد صرامة فتتجاوزها جميعًا: لا نص حرفي من أي هيئة معايير مرخَّصة. كل نقطة يختلف فيها ⁨NextPDF⁩ عن دليل مصدري تُسجَّل مع البند المصدري الذي تتجاوزه والسبب. وتستشهد ورقة الأسلوب بمصادرها بالطريقة نفسها التي تفعلها أي صفحة.

جودة لا تضطر إلى تصديقها على عواهنها

يُفرض الانضباط بالأدوات، لا بالنوايا الحسنة:

Scaffold The page starts from a populated front-matter and section skeleton.
Vale packs Apple, MSTP, Google, and controlled-vocabulary rules run on the prose.
Link check docs:link-check rejects link rot against the built site.
NDA scan docs:nda-scan rejects private FQCNs and internal artefact names.
Quote fingerprint docs:jaccard-fingerprint flags verbatim standards-text reuse.
Citation audit docs:rag-citation-check / docs:rag-fallback-check guard the digests.
Review A reviewer confirms the page's declared evidence level holds.

بوابات جودة التوثيق، بالترتيب الذي تجتازها به الصفحة: يثبِّت الهيكل المعبَّأ البنيةَ؛ ويفرض Vale حِزَم الصوت؛ وتفرض بوابات docs:* سلامة الروابط، ونظافة الاستشهادات، وعدم وجود نص حرفي من المعايير، وعدم تسرُّب أي محتوى خاص؛ وتؤكِّد المراجعة أساس الدليل. الصفحة التي تفشل في بوابة هي خلل، يُعامَل مثل اختبار فاشل.

تطابق هذه البوابات إدخالات حقيقية في composer.json داخل هذا المستودع. يشغِّل docs:lint بوابتي NDA والروابط محليًا. ويضع docs:jaccard-fingerprint علامة على إعادة استخدام نص المعايير حرفيًا عند تجاوز حد تشابه محدد. أما docs:rag-fallback-check فهو منفِّذ مكتمل، يعمل دون اتصال وبسلوك حتمي، لبروتوكول سلامة الاستشهادات. أُوصِل التحقُّق الحي من RAG (docs:rag-citation-check) وبعض الماسحات كبوابات، مع استمرار بناء مشغِّلاتها الأعمق. والقول الصريح هو: العقد مُعتمد، والفحوص البنيوية مفروضة اليوم؛ أما حملة جعل كل فحص شاملًا فما زالت مستمرة. لا يدّعي Insider_ لوحة خضراء لم يكتسبها — وهذا بحد ذاته تطبيق لمعيار “الصحة” في نموذج الجودة على هذه الصفحة.

ماذا تقول الأدلة

هذه الصفحة Evidence: Standard-backed في ادعاءات جودة التوثيق، ومستندة إلى المستودع في ادعاءات الفرض. هذا الأساس المزدوج مقصود: المبادئ تأتي من المعايير؛ أما الفرض فيمكن التحقق منه بقراءة المستودع.

الادعاء	الأساس	المرتكز
للتوثيق معيار جودة محدَّد	معيار	دقيق، بمفردات واحدة، مفهوم للقارئ، يذكر ما يلزم مع اكتماله، ومتاح للتقنيات المساعِدة Spec: ISO/IEC/IEEE 26514, §8
المصطلحات محكومة	معيار	مصطلحات متّسقة عبر مجموعة المعلومات Spec: ISO/IEC/IEEE 26514, §8
البنية تسبق الكتابة	معيار	تحليل الجمهور والمهام قبل التصميم Spec: ISO/IEC/IEEE 26514, §9
تأتي العبارة الأكثر فائدة أولًا	معيار	أهم رسالة في البداية Spec: ISO 24495-1, §5
تُشحن المستندات مع الشيفرة	معيار	تتضمن مخرجات كل تكرار معلومات المستخدم Spec: ISO/IEC/IEEE 26515, §Introduction
الجودة مُتحقَّق منها آليًا	داخل المستودع	بوابات `composer.jsondocs:*`؛ و`docs/style/nextpdf-overrides.md` المعتمَدة؛ وإعداد ⁨Vale⁩ الفعّال

مثال عملي

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

<?php

declare(strict_types=1);

// Illustrative: the documentation build's contract for a quality datum.
// The component throws if no real value is supplied — a metric is never
// allowed to live as a hardcoded literal that can drift out of date.
final class QualityDatum
{
    public function __construct(
        public readonly string $label,
        public readonly string $value,
    ) {
        if ($this->value === '') {
            throw new \InvalidArgumentException(
                'A quality datum must carry a verified value; '
                . 'documentation never invents a metric.',
            );
        }
    }
}

$phpstanLevel = new QualityDatum(label: 'PHPStan', value: 'Level 10');

المغزى هو الـ throw. معيار “الصحة” في نموذج جودة المعلومات ليس إرشاديًا هنا؛ فالبنية تفرضه كي لا يُشحَن رقم قديم بصمت.

مفهوم خاطئ شائع

الفخّ هو قراءة “التوثيق باعتباره منتجًا” باعتبارها شعارًا عن الصقل — نصوص أجمل، وصفحات أبهى. وهذا عكس الشكليات. فالمعنى أن المستندات تحمل معيارًا محدَّدًا للجودة، ومفردات محكومة، وبنية مجمَّدة، وبوابات تتحقق منها الأدوات آليًا. الصفحة التي تفشل في أي منها هي خلل له إصلاح، يُعالَج مثل اختبار فاشل. الصقل نتيجة جانبية للانضباط، لا غايته.

الفخّ الثاني هو افتراض أن كل بوابة شاملة بالفعل لمجرد وجود العقد. وهذا غير صحيح، وتقول هذه الصفحة ذلك بوضوح. الفحوص البنيوية مفروضة اليوم؛ أما المُحقِّقات الأعمق فما زالت قيد الإنشاء. وادّعاء خلاف ذلك من شأنه أن ينتهك نموذج الجودة ذاته الذي تصفه هذه الصفحة.

الحدود والقيود

تصف هذه الصفحة انضباط التوثيق. وهي ليست ورقة الأسلوب، ولا ملف التصنيف، ولا تطبيقات البوابات نفسها. وهي لا تؤكد أي سلوك للمحرك. المصنوعات المرجعية موجودة داخل المستودع (docs/style/nextpdf-overrides.md، والتصنيف المجمَّد، وسكربتات composer.json docs:*) وهي المرجع الأعلى على أي ملخص هنا عند الاختلاف.

سطح الفرض جزئي باعتراف صريح. فحص سلامة الاستشهادات الاحتياطي فعّال. وتعمل بوابتا الروابط واتفاقية عدم الإفصاح محليًا. أما مُحقِّقا الاقتباس الحرفي والاستشهاد الحي فموصولان، مع بقاء مُشغِّلاتهما الشاملة قيد الإنزال. يُبلَّغ عن هذا بوصفه عملًا قيد التنفيذ، لا منجَزًا. وحيثما تمس هذه الصفحة توثيق فئة ⁨Premium⁩، ينطبق الانضباط الموصوف على مستوى العملية، لا على مستوى أي آلية غير عامة إطلاقًا.

مستندات ذات صلة

انضباط الاستشهاد — القاعدة الأشد صرامة في تسلسل الأسلوب الهرمي، ونظام مستوى الدليل الذي تستند إليه هذه الصفحة.
مشهد المعايير — المعايير التي يستشهد بها هذا الانضباط، وكيف يتحول أي بند إلى سلوك موثَّق.
فلسفة تصميم ⁨NextPDF⁩ — الذوق الهندسي الذي يعامل خلل التوثيق مثل خلل الشيفرة.

مسرد المصطلحات

نموذج جودة المعلومات — إعادة صياغة ⁨NextPDF⁩ لمعايير معلومات المستخدِم في §8 من ⁨ISO 26514⁩ (دقيقة، وبمفردات واحدة، ومفهومة للقارئ، وتذكر ما يلزم مع اكتمالها، وفي متناول التقنيات المساعِدة) المستخدَمة بوصفها معيار المراجعة لكل صفحة ⁨Insider_⁩‎.
اللغة الواضحة — تواصل تتيح صياغته وبنيته وتصميمه للقراء المقصودين إيجاد المحتوى وفهمه واستخدامه؛ وهي خط أساس يُطبَّق عبر الأوضاع، لا نوع محتوى.
تسلسل الأسلوب الهرمي — المجموعة المعتمَدة متعددة الطبقات من أدلة الأسلوب المصدرية (⁨Apple⁩، و⁨Microsoft⁩، و⁨Google⁩، إضافةً إلى خطوط أساس اللغة الواضحة والمفردات المضبوطة) مع تسجيل كل اختلاف في ⁨NextPDF⁩ مقابل مصدره.
بوابة الجودة — فحص آلي (حزمة ⁨Vale⁩ أو سكربت composer docs:*) يجب أن تجتازه الصفحة؛ والفشل خلل في التوثيق، لا هنة.
بيانات ⁨front-matter⁩ الوصفية — الترويسة القابلة للقراءة آليًا (section، وaudience، وevidence_level، وtags) التي تجعل الصفحة قابلة لتحديد الموضع والتصنيف، وفق اشتراط تنظيم الموضوعات.