المطورين لماذا يجب عليك عدم تخطي الوثائق

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

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

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

التوثيق الجيد يساعد المستخدمين

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

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

ومن شأن التصميم الجيد للتخطيط أيضًا أن يساعد المستخدمين حقًا في الفحص من خلال كل قسم من الوثائق دون إجهاد العين. بعض الأمثلة الجيدة (المعروفة أيضًا باسم مفضلاتي) هي وثائق Bootstrap و WordPress ' “الخطوات الأولى مع وورد”.

يساعد المطورين الآخرين أيضًا

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

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

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

الغريب أنه يساعد أيضا المبرمج

الشيء المضحك في الترميز هو أنه في بعض الأحيان حتى المطورين أنفسهم لا يفهمون الكود الذي كتبوه. هذا صحيح بشكل خاص في الحالات التي تم فيها ترك الرموز دون مساس لعدة أشهر أو حتى سنوات.

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

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

ما الذي يجعل للحصول على وثائق جيدة?

هناك العديد من العوامل لبناء جزء جيد من الوثائق.

1. لا تفترض أبدًا

لا تفترض أن المستخدمين يعرفون ماذا أنت تعرف كذلك ماذا هم تريد أن تعرف. هو دائما أفضل للبدء من البداية بغض النظر عن مستوى كفاءة المستخدمين.

إذا قمت ببناء مكون إضافي jQuery ، على سبيل المثال ، يمكنك أن تستلهم من وثائق SlickJS. إنه يوضح كيفية هيكلة HTML ، حيث يتم وضع CSS وجافا سكريبت ، وكيفية تهيئة المكون الإضافي jQuery في مستواه الأساسي ، وحتى يظهر الترميز النهائي الكامل بعد إضافة كل هذه الأشياء ، وهو أمر واضح.

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

2. اتبع المعيار

في إضافة الوثائق التي تتماشى مع رمز, استخدم المعيار المتوقع للغة. من الجيد دائمًا وصف كل دالة والمتغيرات وكذلك القيمة التي يتم إرجاعها بواسطة الوظيفة. فيما يلي مثال على الوثائق المضمنة الجيدة لـ PHP.

 / ** * إضافة فئات مخصصة إلى صفيف فئات الجسم. * *param صفيف فئات $ الطبقات للعنصر الجسم. *return array * / function body_classes ($ classes) // يضيف فئة من مدونة المجموعة إلى المدونات التي تضم أكثر من مؤلف منشور. if (is_multi_author ()) $ classes [] = 'group-blog'؛  عودة الطبقات $ ؛  add_filter ('body_class'، 'body_classes')؛ 

فيما يلي بعض المراجع القليلة لتنسيق الوثائق المضمّنة مع أفضل الممارسات في PHP و JavaScript و CSS:

• PHP: PHP الوثائق القياسية لورد
• جافا سكريبت: UseJSDoc
• CSS: CSSDoc

إذا كنت تستخدم SublimeText ، أود أن أقترح تثبيت DocBlockr الذي سيقوم بملء الرمز الخاص بك بذكاء مع الوثائق المضمّنة.

3. العناصر الرسومية

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

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

4. التقسيم

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

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

5. مراجعة وتحديث

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