يُعَدّ التوثيق التقني أمرًا ضروريًا في تحسين تجربة المستخدم، حيث يوفر إرشادات واضحة حول كيفية استخدام منتج أو تطبيق ويشجعهم على استخدامه وتجربته، يقدم هذا المقال نظرة عامة على المبادئ الأساسية لكتابة التوثيقات التقنية، ويسلّط الضوء على أفضل الممارسات لإنشاء وثائق واضحة وسهلة الفهم. وسواء كنتم بحاجة لتوثيق مشاريعكم أو منتجاتكم البرمجية، أو كتابة أي محتوى تقني آخر، سيساعدكم تطبيق المبادئ التي سنشرحها في الفقرات التالية على كتابة التوثيقات التقنية بجودة عالية.
ما هو التوثيق التقني
التوثيق التقني هو بمثابة دليل استخدام أو كتيب إرشادات خاص بتقنية ما، حيث يركز على توفير معلومات تفصيلية للمطورين والمستخدمين، ويتضمن وصفًا تفصيليًا حول طريقة التعامل معها، وشرحًا للتفاصيل الفنية الخاصة بها من دوال وواجهات برمجية، ومعلومات عن صيانتها وحل المشكلات الشائعة التي قد تواجههم عند التعامل معها.
لنتعرف على أهم النصائح الواجب اتباعها لكتابة التوثيقات التقنية بوضوح واحترافية.
أولًا: الالتزام بالوضوح والإيجاز والاتساق
تشكل هذه العناصر الثلاثة المبادئ الأساسية لكتابة التوثيقات التقنية، وتساعد في إنشاء وثائق عالية الجودة، ولنوضح كل عنصر من هذه العناصر بمزيد من التفصيل.
الوضوح
كي يحقق التوثيق التقني سمة الوضوح، يتوجب علينا تطبيق الإرشادات التالية:
- استخدام كلمات بسيطة ولغة واضحة ووضع الجمهور المستهدف في الحسبان
- الوضوح عند كتابة تعليمات لتنفيذ دالة ما، ويفضل استخدام الأفعال المبنية للمعلوم لتوضيح الفاعل وتحديد هل ستُشَغّل الدالة بواسطة حدث معين، أم على المستخدم استدعاؤها بشكل صريح
- شرح المصطلحات الجديدة بوضوح، حيث يساعد ذلك في وضع أساسيات للمفاهيم التي سنتحدث عنها لاحقًا
- استبدال الضمائر بأسماء علم إن كانت تشير لأكثر من شيء واحد في السياق المحدد
- تقديم فكرة واحدة في كل جملة لتحسين المقروئية، والالتزام بفكرة رئيسية واحدة في كل فقرة
- ربط كل جملة منطقيًا بالجمل التي قبلها، كما لو أن كل جملة في الفقرة هي حلقة في سلسلة، فإن فهمنا الحلقة الأولى، فيجب أن تتبعها الحلقات الأخرى في السلسلة، لتشكل سلسلة مترابطة تتدفق فيها الأفكار بسلاسة
الإيجاز
من الجيد إبقاء الجمل قصيرة وموجزة قدر المستطاع لتعزز وضوح المستند وسهولة قراءته، وتساعد على الفهم السريع، فقد يكون فهم الجمل الطويلة أصعب بسبب بنيتها المعقدة. وبناءً على معايير سهولة القراءة الشائعة، من الأفضل كتابة 15 إلى 20 كلمة وسطيًا في كل جملة. وللحصول على معلومات إضافية حول هذا المعيار ننصح بمطالعة صفحة المقروئية على ويكيبيديا.
الاتساق
يتوجب علينا استخدام نفس المصطلحات في التوثيق البرمجي لضمان تجربة قراءة سلسة. على سبيل المثال، إذا استخدمنا مصطلح وكلاء المستخدم user agents للإشارة إلى المتصفحات browsers، فعلينا الالتزام بهذا المصطلح في كل السياق، إذ يجنبنا ذلك الالتباس الذي قد ينشأ نتيجة لاستخدام مصطلحات عدة، حتى لو كان لها المعنى نفسه.
كما ينبغي اتباع أسلوب تنسيق موحد في جميع الوثائق، والحفاظ على تناسق الكلمات، من حيث استخدام الأحرف الكبيرة والصغيرة -في حال استخدام اللغة الإنجليزية في التوثيق- إذ تُحَسّن هذه الممارسات مقروئية المستند، وتظهره بشكل احترافي.
ثانيًا: تنظيم المحتوى
ينبغي أن نطبّق نفس القواعد المستخدمة لتنظيم الشيفرات البرمجية عند تنظيم المحتوى التقني، وذلك من خلال تحديد هدف واضح للمحتوى، والتفكير في البنية التي نريد اعتمادها في التوثيقات. والحرص على أن تساهم كلّ الأقسام الفرعية في تحقيق هذا الهدف تدريجيًا، ولنوضح أهم الأقسام التي تساعدنا على تنظيم محتوانا التقني.
مقدمة التوثيق
أولاً، علينا وصف الميزة التقنية التي سنوثّقها في المقدمة، ونوضّح لماذا سيكون التعرف على تلك الميزة مفيدًا كأن نذكر حالات عملية مفيدة لاستخدامها. فكلما أضفنا حالات واقعية ذات أهمية، سَهُلَ على القراء فهم المحتوى والتفاعل معه.
التسلسل المنطقي
ستساعدنا الأسئلة التالية في تنظيم المحتوى وفق تسلسل منطقي صحيح:
- هل التوثيق مصمم لتوجيه القراء بدايةً من المفاهيم الأساسية إلى المفاهيم المتقدمة
- هل توجد أقسام مخصصة للتعريف بالأساسيات النظرية وكل ما يلزم، قبل الانتقال إلى كيفية التنفيذ
- هل تُماثِل بنية المستند مسار التعلم الطبيعي للموضوع، فهذا يساعد على بناء المعلومات خطوة خطوة ويعزز تجربة التعلم
- هل توجد أدلة إرشادية وأمثلة كافية تعزز الأقسام النظرية والمفاهيمية
- هل يتبع المحتوى تسلسلاً منطقيًا من حيث الجمل والفقرات والأقسام
- وهل يعتمد كل قسم على المعلومات السابقة، مع تجنب الفجوات في المحتوى
استخدام الأمثلة
استخدام الأمثلة في التوثيق البرمجي أمر بالغ الأهمية ويساعدنا على توصيل الفكرة بوضوح وسهولة، يمكن أن نتخيل أننا نجلس بجوار شخص ما ونشرح له المفاهيم، كما يمكن أن نستبق أسئلته ونعالجها في الكتابة، ونستخدم هذا الأسلوب لإضافة أكبر عدد ممكن من الأمثلة الواضحة ذات الصلة بما نشرحه.
وعند كتابة التوثيق البرمجي، ليس بالضرورة أن نقتصر على تقديم الأمثلة البرمجية فقط بل يمكننا أيضًا تضمين أمثلة عملية وحالات غير برمجية تساعد في توضيح فائدة الميزة وكيفية استخدامها وتطبيقها عمليًا. هذا سيساعد القراء على استيعاب المفاهيم بصورة أفضل ويلبي أيضًا أنماط التعلم المختلفة.
ثالثًا: تحسين بنية التوثيق
من الضروري تقييم بنية مستندات التوثيق للتأكد من أنها تحافظ على تسلسل هرمي منطقي ومتوازن باتباع الإرشادات التالية:
- يجب أن يكون لكل قسم رئيسي ولكل قسم فرعي غرض واضح، ولا يجب أن يكون هناك أقسام بلا هدف محدد أو بلا محتوى كافٍ
- التعامل مع الأقسام اليتيمة Orphan Sections وهي الأقسام الرئيسية التي تحتوي على قسم فرعي واحد فقط، كأن يكون لدينا قسم فرعي واحد من المستوى الثالث H3 ضمن قسم رئيسي من المستوى الثاني H2، هذا يشير لضرورة إعادة توسيع هذا القسم أو دمجه مع قسم آخر
- التحقق من عدم وجود الكثير من العناوين من المستوى الرابع H4، فكثرة الأقسام الفرعية قد يكون مرهقًا للقراء، وقد يُصعّب عليهم فهم المعلومات
- الانتباه للطول الإجمالي لكل قسم فإذا كان أحد الأقسام طويلًا جدًا، فقد يشتت القارئ، لذا نقسّم الأقسام الكبيرة لأقسام فرعية منطقية متعددة، أو نعيد هيكلة المحتوى
تدقيق المحتوى
من أكثر الخطوات أهمية في التوثيق البرمجي هي المراجعة الذاتية وتدقيق المحتوى، سواء كنا بصدد إنشاء مستند كبير أو فقرة قصيرة، فهذه الخطوة ضرورية جدًا. لذا نحتاج لأن نخصص وقتًا مناسبًا لمراجعة العمل كاملًا ونحدد الأقسام التي يمكن تحسينها وتوضيحها أكثر، ونزيل الحشو من الأفكار التي لا تضيف قيمة، ونتخلص من الكلمات والعبارات المكررة. ستضمن هذه التعديلات وضوح النص وتماسكه ووصول الأفكار على النحو المطلوب.
كما نحتاج لتدقيق المحتوى لغويًا ويفضل أن نستريح قليلًا قبل مراجعته مرة أخرى، ونبحث عن أي تناقضات في الأسلوب أو أزمنة الأفعال أو التنسيق ثم نعدّل ما يلزم فالمراجعة بعد فترة من الاستراحة تمكننا من ملاحظة الأخطاء التي قد تفوتنا أول مرة.
نصائح إضافية
نختم بجملة من النصائح التالية لتحسين وضوح الوثائق التقنية:
- استخدام القوائم ذات التعداد الرقمي عندما يتوجب علينا اتباع الخطوات بترتيب محدد، أو التعداد النقطي عندما لا يكون للعناصر ترتيب محدد، ونسبق القائمة دائمًا بجملة أولية توضح السياق
- استخدام الفواصل وعلامات الترقيم المناسبة لتحسين المقروئية وتوضيح بنية الجملة
- وضع نص بديل Alternative text للصور، وإرفاق ملفات الفيديو والصوت بنصوص وصفية لجعل الوثائق مناسبة للجميع
- الحرص على أن تكون جميع نصوص الروابط واضحة وتشير بوضوح إلى وجهة الرابط لمساعدة الأشخاص الذين يستخدمون برامج قراءة الشاشة على فهم وجهة الروابط. مثلًا، نستخدم الجملة التالية اطلع على بعض الأدوات مجانية لتحسين محركات البحث بدلاً من جملة انقر هنا
- استخدام لغة مناسبة ومفردات تحترم تنوع الجمهور، وتجعل من الوثائق موضع ترحيب للجميع
الخاتمة
بهذا وصلنا إلى نهاية مقالنا الذي قدمنا فيه نصائح مفيدة للمطورين والكتّاب التقنيين المهتمين بتحسين جودة التوثيقات التقنية والبرمجية. ولنتذكر في الختام أن إنشاء توثيقات تقنية فعالة وسهلة الاستخدام عملية مهمة تبدأ بفهم الجمهور المستهدف والهدف من الوثائق التي نكتبها، مع الحرص على تطبيق المبادئ التي تعلمناها لتحسين جودة الوثائق وفهمها.
ترجمة، وبتصرّف، للمقال Creating effective technical documentation لكاتبته Dipika Bhattacharya.
أفضل التعليقات
لا توجد أية تعليقات بعد
انضم إلى النقاش
يمكنك أن تنشر الآن وتسجل لاحقًا. إذا كان لديك حساب، فسجل الدخول الآن لتنشر باسم حسابك.