سيساعد التوثيق الجيد للبرامج ، سواء كان وثائق المواصفات للمبرمجين والمختبرين ، أو المستندات الفنية للمستخدمين الداخليين ، أو الكتيبات وملفات التعليمات للمستخدمين النهائيين ، المستخدمين على فهم ميزات البرنامج ووظائفه. التوثيق الجيد هو وثائق محددة وواضحة وذات صلة ، مع جميع المعلومات التي يحتاجها المستخدم. ستوجهك هذه المقالة لكتابة وثائق البرنامج للمستخدمين التقنيين والمستخدمين النهائيين.
خطوة
الطريقة 1 من 2: كتابة وثائق البرنامج للمستخدمين التقنيين
الخطوة 1. تعرف على المعلومات التي يجب تضمينها
يتم استخدام وثيقة المواصفات كدليل مرجعي لمصممي الواجهة والمبرمجين الذين يكتبون التعليمات البرمجية والمختبرين الذين يتحققون من أداء البرنامج. تعتمد المعلومات التي يجب تضمينها على البرنامج الذي يتم إنشاؤه ، ولكن قد تتضمن ما يلي:
- الملفات المهمة في التطبيق ، مثل الملفات التي أنشأها فريق التطوير ، وقواعد البيانات التي يتم الوصول إليها أثناء تشغيل البرنامج ، وتطبيقات الجهات الخارجية.
- الوظائف والروتينات الفرعية ، بما في ذلك شرح استخدام الوظيفة / الروتين الفرعي وقيم الإدخال والإخراج.
- متغيرات وثوابت البرنامج وكيفية استخدامها.
- الهيكل العام للبرنامج. بالنسبة للبرامج القائمة على محرك الأقراص ، قد تحتاج إلى وصف كل وحدة ومكتبة. أو ، إذا كنت تكتب دليلاً لبرنامج مستند إلى الويب ، فقد تحتاج إلى توضيح الملفات التي تستخدمها كل صفحة.
الخطوة 2. حدد مستوى التوثيق الذي يجب أن يكون موجودًا وقابل للفصل عن كود البرنامج
كلما زادت الوثائق الفنية المضمنة في كود البرنامج ، كان من الأسهل تحديثها وصيانتها ، وكذلك شرح الإصدارات المختلفة من البرنامج. كحد أدنى ، يجب أن تتضمن الوثائق في كود البرنامج استخدام الوظائف والروتينات الفرعية والمتغيرات والثوابت.
- إذا كانت شفرة المصدر الخاصة بك طويلة ، فيمكنك كتابة الوثائق في ملف تعليمات ، والذي يمكن بعد ذلك فهرسته أو البحث فيه باستخدام كلمات رئيسية معينة. تكون ملفات التوثيق المنفصلة مفيدة إذا كان منطق البرنامج مقسمًا على عدة صفحات ويتضمن ملفات دعم ، مثل تطبيق ويب.
- بعض لغات البرمجة (مثل Java أو Visual Basic. NET أو C #) لها معايير توثيق التعليمات البرمجية الخاصة بها. في مثل هذه الحالات ، اتبع الوثائق القياسية التي يجب تضمينها في التعليمات البرمجية المصدر.
الخطوة 3. حدد أداة التوثيق المناسبة
في بعض الحالات ، يتم تحديد أداة التوثيق من خلال لغة البرمجة المستخدمة. اللغات C ++ و C # و Visual Basic و Java و PHP وغيرها لها أدوات التوثيق الخاصة بها. ومع ذلك ، إذا لم يكن الأمر كذلك ، فستعتمد الأدوات المستخدمة على الوثائق المطلوبة.
- يعد معالج النصوص مثل Microsoft Word مناسبًا لإنشاء ملفات نصية للمستندات ، طالما أن الوثائق موجزة وبسيطة. لإنشاء وثائق طويلة بنص معقد ، يختار معظم الكتاب التقنيين أداة توثيق متخصصة ، مثل Adobe FrameMaker.
- يمكن إنشاء ملفات التعليمات لتوثيق التعليمات البرمجية المصدر باستخدام برنامج إنشاء ملفات الدعم ، مثل RoboHelp أو Help and Manual أو Doc-To-Help أو MadCap Flare أو HelpLogix.
الطريقة 2 من 2: كتابة وثائق البرامج للمستخدمين النهائيين
الخطوة 1. تعرف على أسباب العمل الكامنة وراء إنشاء الدليل
في حين أن السبب الرئيسي لتوثيق البرنامج هو مساعدة المستخدمين على فهم كيفية استخدام التطبيق ، إلا أن هناك عدة أسباب أخرى قد تكمن وراء إنشاء الوثائق ، مثل مساعدة قسم التسويق في بيع التطبيق ، وتحسين صورة الشركة ، وتقليل الدعم الفني التكاليف. في بعض الحالات ، يلزم التوثيق للامتثال للوائح أو المتطلبات القانونية الأخرى.
ومع ذلك ، فإن التوثيق ليس بديلاً جيدًا للواجهة. إذا كان التطبيق يتطلب الكثير من الوثائق للعمل ، فيجب تصميمه ليكون أكثر سهولة
الخطوة 2. تعرف على الجمهور المستهدف من الوثائق
بشكل عام ، يمتلك مستخدمو البرامج معرفة محدودة بالكمبيوتر تتجاوز التطبيقات التي يستخدمونها. هناك عدة طرق لتلبية احتياجات التوثيق الخاصة بهم:
- انتبه إلى عنوان مستخدم البرنامج. على سبيل المثال ، يفهم مسؤول النظام عمومًا تطبيقات الكمبيوتر المختلفة ، بينما يعرف السكرتير فقط التطبيقات التي يستخدمها لإدخال البيانات.
- انتبه لمستخدمي البرامج. على الرغم من أن وظائفهم متوافقة بشكل عام مع المهام التي يتم إجراؤها ، إلا أن هذه الوظائف قد يكون لها أعباء عمل مختلفة ، اعتمادًا على مكان العمل. من خلال إجراء مقابلات مع المستخدمين المحتملين ، يمكنك معرفة ما إذا كان تقييمك للمسمى الوظيفي الخاص بهم صحيحًا.
- انتبه إلى الوثائق الموجودة. يمكن أن تُظهر وثائق ومواصفات وظائف البرامج ما يحتاج المستخدمون إلى معرفته من أجل استخدامها. ومع ذلك ، ضع في اعتبارك أن المستخدمين قد لا يكونون مهتمين بمعرفة "الأجزاء الداخلية" من البرنامج.
- تعرف على ما يتطلبه الأمر لإكمال المهمة ، وما يتطلبه الأمر قبل أن تتمكن من إكمالها.
الخطوة 3. تحديد التنسيق المناسب للوثائق
يمكن ترتيب وثائق البرامج في تنسيق واحد أو تنسيقين ، وهما الكتب المرجعية والكتيبات. في بعض الأحيان ، يعد الجمع بين التنسيقين حلاً جيدًا.
- تُستخدم تنسيقات المراجع لوصف جميع ميزات البرنامج ، مثل الأزرار وعلامات التبويب والحقول ومربعات الحوار وكيفية عملها. تتم كتابة بعض ملفات التعليمات بهذا التنسيق ، خاصة تلك التي تكون حساسة للسياق. عندما ينقر المستخدم على "تعليمات" في شاشة معينة ، سيتلقى المستخدم الموضوع ذي الصلة.
- يستخدم التنسيق اليدوي لشرح كيفية القيام بشيء ما بالبرنامج. تكون الكتيبات بشكل عام مطبوعة أو بتنسيق PDF ، على الرغم من أن بعض صفحات المساعدة تتضمن أيضًا إرشادات حول كيفية القيام بأشياء معينة. (بشكل عام ، لا تعتبر التنسيقات اليدوية حساسة للسياق ، ولكن يمكن ربطها من موضوعات حساسة للسياق). تكون الكتيبات بشكل عام في شكل دليل ، مع ملخص للمهام التي يتعين القيام بها في وصف ودليل منسق في خطوات.
الخطوة 4. حدد نوع الوثائق
قد يتم حزم وثائق البرنامج للمستخدمين في واحد أو أكثر من التنسيقات التالية: كتيبات مطبوعة أو ملفات PDF أو ملفات تعليمات أو تعليمات عبر الإنترنت. تم تصميم كل نوع من أنواع الوثائق ليوضح لك كيفية استخدام وظائف البرنامج ، سواء كان دليلًا أو برنامجًا تعليميًا. قد تتضمن صفحات التوثيق والمساعدة عبر الإنترنت أيضًا مقاطع فيديو توضيحية ونصًا وصورًا ثابتة.
يجب فهرسة ملفات التعليمات والدعم عبر الإنترنت ويمكن البحث فيها باستخدام الكلمات الأساسية حتى يتمكن المستخدمون من العثور بسرعة على المعلومات التي يحتاجون إليها. على الرغم من أن تطبيق منشئ ملفات التعليمات يمكنه إنشاء فهرس تلقائيًا ، إلا أنه لا يزال يوصى بإنشاء فهرس يدويًا باستخدام الكلمات الأساسية التي يتم البحث عنها بشكل شائع
الخطوة 5. حدد أداة التوثيق المناسبة
يمكن إنشاء كتيبات أو ملفات PDF مطبوعة باستخدام برنامج معالجة كلمات مثل Word أو محرر نصوص متقدم مثل FrameMaker ، اعتمادًا على طول الملف ودرجة تعقيده. يمكن كتابة ملفات التعليمات باستخدام برنامج إنشاء ملفات المساعدة ، مثل RoboHelp أو Help and Manual أو Doc-To-Help أو Flare أو HelpLogix أو HelpServer.
نصائح
- يجب أن يكون نص وثائق البرنامج منظمًا بطريقة تسهل قراءته. ضع الصورة بالقرب من النص المناسب قدر الإمكان. قسّم الوثائق حسب الأقسام والموضوعات منطقيًا. يجب أن يصف كل قسم أو موضوع مشكلة معينة ، كل من ميزات المهمة والبرنامج. يمكن شرح القضايا ذات الصلة بالروابط أو قوائم المراجع.
- يمكن استكمال كل أداة من أدوات التوثيق الموضحة في هذه المقالة ببرنامج صانع لقطات الشاشة ، مثل SnagIt إذا كانت وثائقك تتطلب لقطات شاشة متعددة. مثل أي وثائق أخرى ، يجب عليك أيضًا تضمين لقطات شاشة للمساعدة في شرح كيفية عمل التطبيق ، بدلاً من "إغراء" المستخدم.
- يعد الاهتمام بالأسلوب أمرًا مهمًا للغاية ، خاصةً إذا كنت تكتب وثائق البرامج للمستخدمين النهائيين. خاطب المستخدمين بالضمير "أنت" ، بدلاً من "المستخدم".
