لماذا تعد وثائق OpenBSD جيدة جدًا؟

بقلم Solène في 18 أغسطس 2022 العلامات: #openbsd #documentation

تعليقات على Fediverse / Mastodon

يُعرف نظام التشغيل OpenBSD بأنه آمن ، ولكن أيضًا بامتلاكه توثيقًا دقيقًا وممتازًا. في هذا النص ، سأحاول فهم ما الذي يجعل توثيق OpenBSD رائعًا للغاية.

موقع مشروع OpenBSD على الويب

فيما يلي قائمة بالوسائط المستخدمة لنشر المعلومات: أول بريد إلكتروني أثناء التثبيت صفحات الدليل موقع انترنت الأسئلة المتداولة حول موقع الويب أمثلة النشرات الإخبارية للإعلان

دعونا ندرسها واحدة تلو الأخرى.

بعد تثبيت OpenBSD ، عند تسجيل الدخول كجذر لأول مرة ، يتم الترحيب بك برسالة تفيد بأنك تلقيت بريدًا إلكترونيًا. في الواقع ، هناك بريد إلكتروني من Theo De Raadt مكتوب وقت التثبيت يرحب بك في OpenBSD. يمنحك بعض النصائح حول كيفية البدء ، ولكن الأهم من ذلك أنه يأخذك إلى صفحة الدليل (8) بعد التمهيد.

توصف صفحة الدليل اللاحقة (8) بأنها "أشياء يجب التحقق منها بعد التمهيد الكامل الأول" ، وستوجهك خلال التغييرات الأكثر شيوعًا التي قد ترغب في إجرائها على نظامك. والأهم من ذلك ، أنه يشرح كيفية استخدام صفحة الدليل ، مثل النظر إلى قسم "انظر أيضًا" الذي يؤدي إلى صفحات دليل أخرى مرتبطة بالصفحة الحالية.

صفحة الدليل اللاحقة (8)

صفحات الدليل هي طريقة لشحن الوثائق مع البرنامج ، وعادة ما تجد صفحة دليل تحمل نفس اسم الأمر أو ملف التكوين الذي تريد توثيقه. يبدو أن صفحات الرجل ظهرت عام 1971 ، "الرجل" تعني اليدوي.

صفحة ويكيبيديا في صفحة الدليل

تعد الصفحات البشرية أساسًا لوثائق OpenBSD ، فهي تتبع معايير معينة وتحتوي على الكثير من البيانات الوصفية. عندما تكتب صفحة رجل ، فأنت لا تكتب نصًا فحسب ، بل تصف نصك. على سبيل المثال ، عندما نحتاج إلى الرجوع إلى صفحة دليل أخرى ، فسنستخدم علامة "الإسناد الترافقي" ، وهذا التنسيق المنسق يسمح بالعرض الدقيق ولكن أيضًا عمليات البحث الدقيقة.

عندما نشير إلى صفحة في محادثة نصية ، غالبًا ما نكتب اسمهم ، بما في ذلك القسم ، مثل رجل (1). إذا رأيت رجل (1) ، فأنت تدرك أن هذه صفحة دليل لـ "man" في القسم الأول. هناك 9 أقسام لصفحة الدليل ، وهي طريقة قديمة لتصنيفها إلى فئات ، لذا إذا كان هناك شيئين يحملان الاسم نفسه ، يمكنك استخدام القسم لتمييزهما عن بعضهما البعض. فيما يلي مثال ، سيخرج "man passwd" passwd (1) ، وهو برنامج لتغيير كلمة مرور المستخدم ، ومع ذلك قد ترغب في قراءة passwd (5) الذي يصف تنسيق الملف / etc / passwd ، في هذا إذا كنت ستستخدم "man 5 passwd". لطالما وجدت أن هذه الطريقة للإشارة إلى صفحات الرجال مفيدة جدًا.

في OpenBSD ، توجد صفحات دليل لكافة برامج النظام الأساسية وملفات التكوين. نحاول دائمًا أن نكون متسقين للغاية في كيفية تقديم المعلومات ، ويتم اختيار الصياغة بعناية لتكون واضحة قدر الإمكان. إنها جهد مشترك يشارك فيه العديد من المراجعين ، ويجب الموافقة على التغييرات من قبل عضو واحد على الأقل من الفريق. عند تعديل برنامج OpenBSD ، يجب تحديث صفحة الدليل وفقًا لذلك. يتم أيضًا تحديث الصفحات من حين لآخر لتشمل المزيد من التاريخ الذي يشرح أصول الأوامر ، وهو دائمًا غني بالمعلومات.

بالنسبة إلى الحزم ، لا يوجد ضمان لأننا نجمع فقط البرامج الأولية ، وقد لا توفر صفحة دليل. ومع ذلك ، يوفر مشرفو الحزم ملف "pkg-readme" للحزم التي تتطلب ضبطًا محددًا للغاية ، ويمكن العثور على هذه الملفات في / usr / local / share / doc / pkg-readmes /.

قارئ الصفحة اليدوي عبر الإنترنت OpenBSD: التنسيق الغني يضيء هنا موقع انترنت §

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

موقع OpenBSD على الويب أسئلة وأجوبة §

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