كيفية كتابة التوثيق التقني

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

قبل أن تكتب

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

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

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

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

كيفية كتابة التوثيق التقني

• اكتب النتيجة أولًا. قل ما الذي سيتمكن القارئ من فعله بعد أن تعمل الصفحة. مثال: «بنهاية الخطوات، سيكون تطبيق مرحلة الاختبار متصلًا بـ Stripe».
• استخدم تسلسلًا بسيطًا: الهدف، ما تحتاج إليه، الخطوات، النتيجة، الإصلاحات. هذا يحافظ على سلاسة التقدم للقارئ.
• اكتب إجراءً واحدًا لكل خطوة. «افتح وحدة تحكم الإدارة. اختر Billing. اختر Add payment method.» هذا أسهل في المتابعة من فقرة طويلة فيها خمسة أفعال.
• استخدم الأسماء الدقيقة للأزرار والحقول والمجلدات والأوامر ورموز الأخطاء وأسماء الملفات. إذا كانت الشاشة تعرض Add payment method، فلا تغيّرها إلى New card في المستند.
• ثبّت المصطلحات. إذا قلت workspace في الخطوة 1، فلا تنتقل إلى project area في الخطوة 4.
• ضع المشكلة المحتملة بجانب الخطوة التي تسببها. إذا كان الوصول هو المشكلة غالبًا، فاذكر ذلك هناك. مثال: «إذا كان الزر مفقودًا، فتحقق من أن لديك صلاحية Billing Admin».
• استخدم أمثلة قابلة للنسخ للبرامج والكود. اعرض الأمر، ثم اعرض النتيجة المتوقعة بعده مباشرة. هذا يساعد القارئ على التحقق من شاشته بسرعة.
• اكتب فقرات قصيرة. فكرة واحدة في كل فقرة تكفي. إذا كانت الفقرة تحتوي على أفكار كثيرة، فاقسمها إلى فقرتين.
• احذف أي شيء لا يساعد شخصًا على إنجاز المهمة. الخلفية مفيدة فقط إذا منعت خطأً.
• أضف الخطوة التالية في النهاية. على سبيل المثال، اربط صفحة الاختبار، أو صفحة استكشاف الأخطاء وإصلاحها، أو جزء الإعداد الذي يأتي بعد ذلك.

نموذج بسيط للخطوات

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

مثال لصفحة خاصة بمطور: «شغّل npm install. يجب أن ترى تحديثًا في قائمة الحزم. إذا فشل، فتحقق من تثبيت Node 20». هذا يمنح القارئ شيئًا يفعله، وشيئًا يتوقعه، وشيئًا يتحقق منه.

قبل: «ثم عالج مشكلة الاعتماد». بعد: «شغّل npm install. إذا ظهر لك خطأ صلاحيات، فأعد فتح الطرفية كمستخدم لديه إذن بالكتابة». النسخة الثانية أبطأ في الكتابة وأسرع في الاستخدام.

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

ما الذي يتضمنه التوثيق التقني الجيد

تتبع الصفحة المفيدة عادة هذا الترتيب: العنوان، مقدمة قصيرة، المتطلبات السابقة، الخطوات، النتائج المتوقعة، الإصلاحات، الخطوة التالية. ينجح هذا الترتيب لأنه يجيب عن أسئلة القارئ بالترتيب نفسه الذي تظهر فيه.

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

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

بالنسبة إلى صفحة إعداد بوابة دفع، قد يبدو ذلك هكذا: «اربط Stripe بتطبيق مرحلة الاختبار. تحتاج إلى صلاحية إدارة ومفتاح تجريبي. اتبع الخطوات للصق المفتاح وحفظ الإعداد وتشغيل عملية دفع اختبارية. إذا فشل الاختبار، فتحقق من المفتاح وصلاحيات الحساب. ثم انتقل إلى صفحة إعداد webhook».

اختبره قبل النشر

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

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

إذا خمّن، فالصياغة غير واضحة. استبدل «أدخل القيمة الصحيحة» باسم الحقل الدقيق، أو التسمية، أو مسار الملف.

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

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

للتحقق السريع، مرّ على tools manual check. وإذا كنت تحتاج إلى العادة نفسها للتعليمات المادية، فقارن البنية مع this guide.

ما الذي يخطئ عادة

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

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

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

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

عندما تبدو الصفحة مزدحمة، احذف الزوائد أولًا. احتفظ بالخطوات التي تصل بالقارئ إلى نتيجة تعمل.

المدة التي يستغرقها الأمر

يمكن أن تستغرق صفحة إرشادية قصيرة من 30 إلى 60 دقيقة إذا كان المصدر نظيفًا وكانت المهمة بسيطة.

عادةً ما يستغرق دليل إعداد برنامج عادي من 2 إلى 4 ساعات، بعد احتساب الصياغة، والتحقق من الخطوات، والتحرير.

يمكن أن يستغرق مشروع أكبر، مع الحالات الاستثنائية، ولقطات الشاشة، وجولات المراجعة، معظم يوم.

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

متى يفيد إصدار الفيديو

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

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