الممارسات الجيدة لتطوير البرمجيات الحرة والمفتوحة: التوثيق

التوثيق: الممارسات الجيدة لتطوير البرمجيات الحرة والمفتوحة

التوثيق: الممارسات الجيدة لتطوير البرمجيات الحرة والمفتوحة

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

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

الممارسات الجيدة: التوثيق - مقدمة

علاوة على ذلك ، في حالة معينة من توثيق البرمجيات الحرة أمر حيوي، لأنه يسمح بضمان كامل نقل المعرفة والتمكين اللازمة لتحقيق مرضي 4 حريات التي تروج لها ، وهي:

  • 0: حرية تشغيل البرنامج كيفما شئت ولأي غرض.
  • 1: حرية الوصول إلى البرنامج ودراسته وتغييره أو تكييفه لمصلحتك الخاصة.
  • 2: حرية مشاركة النسخ أو إعادة توزيعها لنشرها و / أو مساعدة الآخرين.
  • 3: حرية توزيع نسخ من إصداراتك المعدلة إلى جهات خارجية.

يجعل التوثيق الجيد من الممكن ، بالتالي ، أن المنتج الذي تم إنشاؤه:

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

الممارسات الجيدة: التوثيق - الملف التمهيدي

الممارسات الجيدة: التوثيق

أساسيات

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

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

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

الممارسات الجيدة بشأن التوثيق في ملفات README النصية

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

بالنسبة لمقالنا ، فقد اتخذنا ملف أفضل الممارسات تصوره وكشف عنها "مبادرة كود التنمية" من بنك التنمية للبلدان الأمريكية، والذي يخبرنا باختصار أن التوثيق الجيد يعتمد على أ ملف نصي README.md (أو .txt) يجب أن يتم تنظيمها على النحو التالي:

موصى به بنية ملف README

  • الوصف والسياق: القسم الذي يجب أن تصف فيه الوظائف والسياق الذي تم تطويره فيه ومشاكل التطوير التي ساعدت في حلها.
  • دليل المستخدم: القسم الذي يجب فيه ذكر التعليمات الموجهة للمستخدم النهائي حول كيفية بدء استخدام الأداة الرقمية.
  • دليل التثبيت: القسم الذي يجب ذكر تعليمات التثبيت الخاصة بإعادة استخدام الأداة الرقمية وتكوينها. هذا القسم مخصص للمطورين.
  • الكتاب قسم حيث يجب منح الائتمانات للمتعاونين في الأداة.
  • ترخيص رمز الأداة: قسم حيث يجب تحديد الأذونات الممنوحة لأطراف ثالثة لإعادة استخدام الأداة الرقمية.
  • ترخيص وثائق الأداة: قسم حيث يجب ذكر نوع الترخيص الوارد في الوثائق التي تم إنشاؤها.

في هذه الممارسات الجيدة، يوصون أيضًا بالإضافة إلى وثائق ملف README لجعلها أكثر اكتمالا ، الأقسام التالية:

  • كيف تساهم: قسم يشرح للمطورين الجدد عملية المساهمة في المشاريع.
  • القواعد السلوكية: يحدد القسم الذي يشرح مدونة قواعد السلوك الأعراف والقواعد والمسؤوليات الاجتماعية التي يجب على الأفراد والمنظمات اتباعها عند التفاعل بأي شكل من الأشكال مع الأداة الرقمية أو مجتمعهم.
  • شارات: قسم يعرض الشارات (الصور الصغيرة المضمنة في README.md) التي تحدد حالة الأداة بطريقة يمكن قراءتها وموجزة.
  • الإصدار: قسم يشير إلى قائمة إصدارات الأداة الرقمية والوظائف المضافة لكل إصدار.
  • شكر وتقدير: قسم يحتوي على شكر وتقدير لأشخاص آخرين أو منظمات ساهمت بطريقة ما في المشروع.

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

اختتام

اختتام

نأمل ذلك هذا "وظيفة صغيرة مفيدة" في «Buenas prácticas» في مجال ال «documentación» لإنشاء عند التطوير «Software libre y abierto»، أن يكون ذا فائدة كبيرة ومفيدة للجميع «Comunidad de Software Libre y Código Abierto» ومساهمة كبيرة في نشر النظام البيئي الرائع والعملاق والمتنامي لتطبيقات ومن أجل «GNU/Linux».

ولمزيد من المعلومات لا تتردد دائما في زيارة أي منها مكتبة على الإنترنت كما OpenLibra y جيديت ليقرأ الكتب (ملفات PDF) حول هذا الموضوع أو غيره مجالات المعرفة. في الوقت الحالي ، إذا أعجبك هذا «publicación», لا تتوقف عن مشاركته مع الآخرين ، في الخاص بك مواقع الويب أو القنوات أو المجموعات أو المجتمعات المفضلة من الشبكات الاجتماعية ، ويفضل أن تكون مجانية ومفتوحة مثل المستودون حيوان بائد شبيه بالفيل، أو الإعجاب الآمن والخاص تیلیجرام.

أو ببساطة قم بزيارة صفحتنا الرئيسية على DesdeLinux أو انضم إلى القناة الرسمية برقية من DesdeLinux لقراءة والتصويت لهذا المنشور أو غيرها من المنشورات الشيقة على «Software Libre», «Código Abierto», «GNU/Linux» والمواضيع الأخرى ذات الصلة بـ «Informática y la Computación»و «Actualidad tecnológica».


كن أول من يعلق

اترك تعليقك

لن يتم نشر عنوان بريدك الإلكتروني. الحقول الإلزامية مشار إليها ب *

*

*

  1. المسؤول عن البيانات: ميغيل أنخيل جاتون
  2. الغرض من البيانات: التحكم في الرسائل الاقتحامية ، وإدارة التعليقات.
  3. الشرعية: موافقتك
  4. توصيل البيانات: لن يتم إرسال البيانات إلى أطراف ثالثة إلا بموجب التزام قانوني.
  5. تخزين البيانات: قاعدة البيانات التي تستضيفها شركة Occentus Networks (الاتحاد الأوروبي)
  6. الحقوق: يمكنك في أي وقت تقييد معلوماتك واستعادتها وحذفها.