نصيحة سيئة: كيف تكتب الوثائق الفنية؟ الجزء الثاني

نصائح لكتابة الوثائق الفنية بكفاءة للمستخدمين.
الجزء 2

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

يمكنك قراءة بداية المقال هنا ، لكننا وصفنا عملية توثيق منتجاتنا وتوطينها في وقت سابق من هذه المقالة .

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



كم عدد المهام الموصوفة في الموضوع - واحدة أو أكثر؟

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

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

أقسام مواضيع المهمة

موضوعات المهمة تتكون من:

• العنوان
• الجزء التمهيدي (باللغة الإنجليزية "مقدمة")
• جمل ، والتي تؤدي إلى وصف لما يحتاج المستخدم إلى فعله بالضبط (باللغة الإنجليزية "عنوان الخطوة")
• مرقمة أو تبدأ بخطوات كبيرة (باللغة الإنجليزية "خطوات مرقمة أو نقطية")
• الجزء الأخير (بالإنجليزية "outro")

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

العنوان

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

اجعل عناوين الصحف رحيقة ، لكن ليس لفترة طويلة في نفس الوقت. قد لا يتم عرض الرؤوس الطويلة بالكامل في بعض المتصفحات أو في Apple Help Viewer.

عند كتابة عنوان رئيسي ، استخدم الضرورة ("افعل هذا")

على سبيل المثال ، "إعداد طابعة باستخدام Bonjour".

لا تستخدم الضرورة في أسماء الموضوعات التي لا تصف كيفية حل المشكلة.

استخدم كلمات سهلة الاستخدام في اسم الموضوع ، ولا تركز على عناصر الواجهة.

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

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

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

إذا كنت تكتب الوثائق باللغة الإنجليزية ، فيجب أن تبدأ الكلمات الموجودة في العنوان بحرف كبير

اليمين : قم بإعداد Mac الخاص بك لاستخدام تطبيقات Windows

خطأ : قم بإعداد Mac الخاص بك لاستخدام تطبيقات Windows

(سنناقش استخدام الأحرف الاستهلالية للعنوان بمزيد من التفاصيل في الجزء التالي من الدليل).

مقدمة (مقدمة)

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

قد تحتوي المقدمة على:

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

استخدام الأجهزة الظاهرية الجاهزة

إذا لم يكن لديك الوقت لإنشاء جهاز ظاهري جديد مع التكوين اللازم ، يمكنك تنزيل الجهاز الظاهري النهائي بتكوين مُعد مسبقًا.

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

على سبيل المثال ، إذا أراد مستخدم Parallels Desktop العمل مع macOS و Windows في نفس الوقت ، كما لو كان نظام تشغيل واحد ، فيمكنك في الجزء التمهيدي التحدث عن "وضع التماسك" من أجل إعداد المستخدم للمصطلحات التي سيتم استخدامها كذلك في الموضوع.

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

لا تقم بإدخال المقدمة في حالة عدم الحاجة إليها.

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

على سبيل المثال:

قم بتشغيل تطبيقات Mac من خلال قائمة Start

افتح قائمة ابدأ في Windows وقم بأحد الإجراءات التالية:

• انقر فوق كافة البرامج> التطبيقات المتوازية المشتركة وحدد التطبيق الذي تريده.
• أدخل اسم التطبيق في حقل البحث وحدد التطبيق المطلوب من الخيارات المقترحة.

لا تجعل المقدمة طويلة جدًا

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

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

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



لا تخبر في مقدمة كيفية إكمال المهمة

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

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



لا تصف نتائج المهمة في الجزء التمهيدي.

يجب أن يتم ذلك في الجزء الأخير ( Outro ).

العبارة قبل التعليمات (Step Heading)

بعد المقدمة ، تحتاج إلى إدراج عبارة "تمهيدية" (باللغة الإنجليزية - "عنوان الخطوة") ، والتي تقود المستخدم إلى الإرشادات: ما يجب القيام به بالضبط لتحقيق نتيجة واحدة أو أخرى.

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

بعد المقدمة يأتي عنوان الخطوة: " لتثبيت Windows: "

ثم الخطوات نفسها:

1) انقر هنا.
2) اختر هذا.
3) وهلم جرا ...

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

إذا كان الموضوع يصف الخطوات المتسلسلة ، فيجب أن يبدو عنوان الخطوة " لعمل شيء:" ("للقيام X:").
على سبيل المثال: "للتبديل إلى وضع ملء الشاشة:" ("لبدء تشغيل Windows:") أو " للتبديل إلى وضع ملء الشاشة:" .

لا تنسى أن تضع القولون في النهاية

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

على سبيل المثال:

1) نجعل الرأس أكثر وضوحًا للمستخدم:

" تعيين Windows لأخذ الشاشة بالكامل"

2) التالي في المقدمة نقدم مصطلح "وضع ملء الشاشة".

3) بعد ذلك ، في خطوة العنوان ، يمكنك بالفعل استخدام المصطلح دون خوف من أنه لن يكون مفهومًا للمستخدم:

" للدخول إلى وضع ملء الشاشة:" ("للدخول إلى وضع ملء الشاشة:")

إذا لم تكن الخطوات الموضحة في الموضوع سلسلة من الإجراءات ، ولكن عدة طرق لتحقيق الهدف ، فيجب القيام بخطوة على النحو التالي: "فيما يلي بعض الطرق للقيام بشيء ما:" ("فيما يلي طرق للقيام X:") أو " للقيام بذلك ، قم بأحد الإجراءات التالية: " (" للقيام X ، قم بأحد الإجراءات التالية: ").

على سبيل المثال ، "فيما يلي طرق لإيقاف تشغيل Windows:") أو " لتوصيل طابعة ، قم بتنفيذ أحد الإجراءات التالية: " ("لتوصيل طابعة ، قم بأحد الإجراءات التالية: ").

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

عنوان الصفحة : تثبيت Windows من قرص التثبيت.
أغطية المهام : تثبيت Windows باستخدام قرص التثبيت.
عنوان الخطوة : لتثبيت ويندوز.

عنوان الصفحة : ضبط إعدادات التماسك.
أغطية المهام : تخصيص كيفية ظهور Windows وتصرفاته في وضع التماسك.
عنوان الخطوة: لتخصيص وضع التماسك.

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

خطوات مرقمة

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

احتفظ بقائمة الخطوات الضرورية قصيرة قدر الإمكان.

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

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

إذا كنت بحاجة إلى وصف عدة طرق لكيفية تنفيذ إجراء في موضوع واحد :

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

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

على سبيل المثال: "لفتح تكوين الجهاز الظاهري ، اختر تصرفات> تكوين أو انقر أيقونة التهيئة في الزاوية العلوية اليمنى.").

ترقيم الخطوات المراد تنفيذها بالتتابع.

من أجل عدم تضخيم الوصف وعدم إبراز تعليمات قصيرة للغاية في خطوات منفصلة (مثل "انقر فوق موافق") ، يمكنك دمج 2 من الإجراءات ذات الصلة والإجراءات ذات الصلة في خطوة واحدة ، كما هو موضح أدناه:



استخدم الرموز النقطية لتسليط الضوء على الإجراءات غير المتسقة

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

على سبيل المثال:


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

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

كما هو موضح في هذا المثال:


إذا كان النص في الموضوع يشير إلى عدة عناصر واجهة عدة مرات ، فقد يكون من المفيد إنشاء موضوع تعليمات منفصل سيتم فيه وصف هذه العناصر.

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

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

الجزء الأخير (Outro)

Outro هي المعلومات النهائية التي تأتي بعد الخطوات المرقمة. حاول أن تجعل الجزء الأخير أقصر - لا تستخدم أكثر من 3 فقرات ، كل منها يتكون من 3 جمل كحد أقصى.

استخدم Outro لوصف نتائج أو نتائج هذه الإجراءات.

مثال على النتيجة أو النتائج قد يكون:

• معلومات حول مكان تثبيت أي ملفات ؛

• تظهر رسالة تتطلب إجراءات إضافية من المستخدم ؛

• الإعدادات التي سيحتاج المستخدم إلى التبديل بعد اكتمال الإجراءات الموضحة.

على سبيل المثال ، الجزء الأخير من الموضوع حول كيفية جعل تشغيل Parallels Access يعمل فقط على Wi-Fi ، يقول ما يلي: " إذا قمت بتكوين Parallels Access للعمل فقط على Wi-Fi ولم يتم اكتشاف أي شبكات لاسلكية حاليًا ، تظهر رسالة تسألك - هل ترغب في الاتصال عبر 3G؟ ".

في الجزء الأخير من الموضوع ، يمكنك وصف طريقة بديلة لإكمال المهمة.

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

يمكن أن يوفر Outro مزيدًا من المعلومات المتعلقة بالمهمة الحالية.

قد تُبلغ هذه المعلومات المستخدمين بما يمكنهم القيام به بعد إكمال المهمة الموضحة.

في المثال التالي ، يصف الموضوع كيفية البحث عن ملف من جهاز ظاهري في برنامج MacOS Finder. وفي الجزء الأخير من الموضوع يصف ماذا يمكن للمستخدم القيام به مع الملف بعد العثور على الملف.



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

على سبيل المثال ، في الجزء الأخير من الموضوع حول دمج أجهزة Windows الافتراضية في نظام التشغيل MacOS ، يمكنك كتابة ما يلي: "إذا كان لديك MacBook Pro 2016 أو إصدار أحدث ، فيمكنك العمل مع بعض تطبيقات Windows باستخدام Touch Bar"


تقسيم المهام الطويلة إلى مراحل قصيرة

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

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



أن تستمر ...

(في الجزء التالي سنتحدث أكثر عن المواضيع والمفاهيم والمرجعية التي تساعد في حل المشكلات)