نصائح لكتابة الوثائق الفنية بكفاءة للمستخدمين.
الجزء 3 (النهائي)
اختتام دليل الكاتب الفني
Andrei Starovoitov ، والذي سيساعد في جعل وثائق المستخدم الخاصة بك أسهل وأكثر قابلية للفهم.
هذه المرة سوف ننظر في مزيد من التفاصيل:
- المواضيع المفاهيمية (صفحات المفهوم) ؛
- موضوعات مرجعية (صفحات مرجعية) ؛
- المواضيع التي تشرح كيفية حل مشكلة (صفحات استكشاف الأخطاء وإصلاحها) ؛
- أين وكيف تستخدم لقطات الشاشة ؛
- وأيضا إعطاء بعض النصائح لأولئك الذين يكتبون الوثائق باللغة الإنجليزية.
الأجزاء السابقة: نهجنا في التوثيق والتعريب ؛ نصائح وثائق
الجزء 1 والجزء 2 .
موضوعات مفاهيمية (صفحات المفاهيم)هناك حاجة إلى مثل هذه المواضيع لتزويد المستخدمين بمعلومات فنية إضافية وبالتالي عدم زيادة تحميل موضوع المهمة.
يرجى ملاحظة أنه ينبغي أن تحتوي على معلومات إضافية بالضبط ، ولكن ليس وسيلة لحل المشكلة.
الموضوعات المفاهيمية جيدة الاستخدام من أجل:
- قل كيف تعمل عملية معينة ؛
- صف الميزات الجديدة التي تمت إضافتها في هذا الإصدار من المنتج ؛
- تزويد المستخدم بمعلومات إضافية من شأنها أن تساعده في اتخاذ قرار ؛
- قل ما يمكن للمستخدم القيام به في التطبيق الخاص بك.
على سبيل المثال ، قد يصف موضوع "حول الأجهزة الظاهرية" ما هو وكيف يعمل. لكن يجب ألا يحتوي هذا الموضوع على إرشادات حول كيفية إنشاء جهاز ظاهري - يجب أن يتم توضيح ذلك في موضوع المهمة.
وبالتالي ، فإن المستخدم المتمرس ، أثناء قراءة موضوع المهمة ، لن يشتكي: "لماذا ترسم لي ما هو ، أعرف بالفعل ...". وأولئك الذين لا يعرفون سيرى رابطًا لموضوع مفاهيمي وقراءته.
عادة ، تبدأ عناوين الموضوعات المفاهيمية بـ:
- "حول (شيء ما)" ("حول الأجهزة الافتراضية") ؛
- "ما هو ...؟" ("ما هي الآلة الافتراضية؟") ؛
- "كيف يعمل (شيء)؟" ("كيف يعمل الجهاز الظاهري؟") ؛
- "فهم أساسيات الجهاز الظاهري" ، إلخ.
فيما يلي مثال لموضوع مفاهيمي من الوثائق الإنجليزية:
المواضيع المرجعية (الصفحات المرجعية) :
تصف هذه المواضيع معلومات مرجعية مختلفة يمكن للمستخدم الرجوع إليها إذا لزم الأمر.
من الأمثلة الجيدة على هذه المواضيع:
- "مسرد" في نهاية الدليل ؛
- موضوع تصف فيه العناصر المتاحة في القائمة وماذا تفعل ، وما هي اختصارات لوحة المفاتيح التي يمكنك استخدامها عند العمل مع البرنامج ، والرموز المتاحة على شريط المهام ، إلخ.
فيما يلي مثال لموضوع يصف رموز واجهة المستخدم الرسومية:
الموضوعات التي تصف كيفية حل مشكلة (صفحات استكشاف الأخطاء وإصلاحها)
مثل هذه المواضيع تساعد المستخدم على التغلب على عقبة أو حل مشكلة. قد تحتوي مشكلات استكشاف الأخطاء وإصلاحها على السيناريوهات التالية:
- المستخدم لديه مشكلة ويريد حلها. على سبيل المثال ، "جهاز USB لا يعمل في جهاز افتراضي".
- حاول المستخدم القيام بشيء وفشل. على سبيل المثال ، "لا أستطيع تنشيط سطح المكتب المتوازي" ("لا يمكنني تنشيط سطح المكتب المتوازي").
- هناك بعض الشرط أو الشرط الذي يريد المستخدم تغييره. على سبيل المثال ، "Windows بطيء" ("Windows يبدو بطيئًا").
ما هو ولا يتم استكشاف الأخطاء وإصلاحها :
إذا كان المستخدم يريد أن يفعل شيئًا ما ، لكنه لا يعرف كيف ، فيجب وصف ذلك ليس في استكشاف الأخطاء وإصلاحها ، ولكن في موضوع المهمة.
يعني استكشاف الأخطاء وإصلاحها أن المستخدم حاول القيام بشيء ما (وفقًا لتعليمات موضوع المهمة) ، ولكن كانت هناك بعض المشكلات ، ولا يعرف المستخدم كيفية حلها.
على سبيل المثال ، الموضوع الذي يصف كيفية استخدام محرك أقراص خارجي في نظام التشغيل الضيف هو موضوع مهمة.
والموضوع الذي يصف المشاكل المحتملة - "أواجه مشكلات في توصيل القرص الصلب" - هو موضوع استكشاف الأخطاء وإصلاحها. يتضمن محتواها أن المستخدم اتبع التعليمات ، لكنه لم ينجح لسبب ما.
إذا كتبت موضوع مهمة ، ويمكن أن تسبب بعض الخطوات في التعليمات صعوبات بسيطة ، فيُسمح لها بوصف ذلك في نفس الخطوة أو الموضوع. بالنسبة للصعوبات البسيطة ، ليس من الضروري كتابة موضوع منفصل لاستكشاف الأخطاء وإصلاحها.
على سبيل المثال ، في نهاية الموضوع الذي يصف كيفية تغيير اختصارات لوحة المفاتيح ، يمكنك إضافة: "بعض مجموعات المفاتيح لا يمكن تحريرها أو حذفها".
استكشاف الأخطاء وإصلاحها المواضيععادةً ما يكون لموضوعات استكشاف الأخطاء وإصلاحها بنية مشابهة لموضوعات المهام.
وهي تتألف من:
- العنوان ("العنوان")
- الجزء التمهيدي ("المقدمة")
- عبارة تمهيدية ، وبعدها تبدأ الخطوات المرقمة أو المعلومات الضرورية ("عنوان الخطوة")
- المعلومات اللازمة لحل مشكلة ("خطوات الحل")
- الجزء الأخير ("outro")
العنوان (عنوان الصفحة)من الجيد أن يعبر رأس موضوع استكشاف الأخطاء وإصلاحها عن مشكلة الشخص الأول للمستخدم. على سبيل المثال:
- "لا أستطيع تنشيط سطح المكتب المتوازي" ("لا يمكنني تنشيط سطح المكتب المتوازي")
- "Windows بطيء" ("Windows يبدو بطيئًا")
- تظهر رسالة "لم يتم اكتشاف أجهزة افتراضية"
إذا كنت تكتب الوثائق باللغة الإنجليزية ، فيجب عليك استخدام الكتابة بالأحرف الكبيرة في العنوان (في الكتابة بالأحرف الكبيرة ، راجع التفاصيل الموجودة في نهاية المقالة):
اليمين: جهاز USB الخاص بي لا يعمل
خطأ: جهاز USB الخاص بي لا يعمل
مقدمة (مقدمة)بعد العنوان مباشرة ، زود المستخدمين بالمعلومات التي يحتاجون إلى معرفتها أولاً.
على سبيل المثال:
- اشرح السبب المحتمل لهذه المشكلة. إذا كان يمكن أن يكون هناك العديد من الأسباب ، صف كل ما هو ممكن
- في بعض الأحيان يمكنك أن تصف بعبارات عامة ما يجب القيام به لحل مشكلة ما. بشكل عام - يجب إعطاء تعليمات مفصلة في خطوات الحل.
عبارة تمهيدية (عنوان الخطوة)قبل تسلسل الخطوات التي تحتاج إلى اتخاذها لحل المشكلة ، اكتب عبارة تمهيدية. لا تنسى أن تضع القولون في النهاية.
إذا كان حل المشكلة هو سلسلة من الإجراءات المتسلسلة:في مثل هذه الحالات ، يجب أن يتم تنفيذ العبارة التمهيدية وفقًا لنفس المبادئ الخاصة بموضوعات المهمة (انظر الجزء الثاني من النصائح) ، أي استخدام نفس الكلمات كما في صياغة المهمة.
على سبيل المثال ، تكتب موضوعًا لاستكشاف الأخطاء وإصلاحها تشرح فيه لماذا لا يمكن للمستخدم فتح تكوين الجهاز الظاهري (عنصر القائمة باللون الرمادي وغير نشط):
العنوان: "لا أستطيع فتح إعدادات الجهاز الظاهري"
مقدمة: "إذا لم تتمكن من فتح إعدادات الجهاز الظاهري (عنصر القائمة باللون الرمادي) ، فإن السبب الأكثر ترجيحًا هو عدم إيقاف تشغيل الجهاز الظاهري."
علاوة على ذلك ، العبارة التمهيدية: "لفتح إعدادات الجهاز الظاهري:" (يتم استخدام نفس الكلمات في هذه العبارة كما هو الحال في صياغة المهمة المراد تنفيذها)
ثم هناك خطوات - 1) تأكد من إيقاف تشغيل الجهاز. إذا كان يعمل ، انقر هنا وهناك. 2) ثم افعل هذا.
إذا كانت المشكلة بها عدة حلول:في مثل هذه الحالات ، يجب أن تحتوي العبارة التمهيدية على الكلمات:
- "جرب هذه الحلول" ،
- "جرب ما يلي" ،
- "تأكد من ذلك" ، إلخ.
فيما يلي بعض الأمثلة من الوثائق الإنجليزية:
عنوان الصفحة: لا أستطيع تنشيط سطح المكتب المتوازي
يغطي المهام: قائمة من الأشياء للتحقق
عنوان الخطوة: إذا كنت تواجه مشكلة في تنشيط Parallels Desktop ، فتأكد من ...
عنوان الصفحة: ويندوز يبدو بطيئا
أغطية المهام: قائمة الأشياء التي يجب تجربتها
عنوان الخطوة: إذا بدا أداء Windows بطيئًا ، فجرب ما يلي ...
عنوان الصفحة: رسالة تقول "لا توجد أجهزة Mac متصلة"
أغطية المهام: عدة أشياء لفحصها أو تجربتها
عنوان الخطوة: إذا كنت لا ترى جهاز Mac الخاص بك في قائمة أجهزة Mac
المعلومات اللازمة لحل المشكلة (خطوات الحل)
يتضمن هذا القسم كل ما يحتاج المستخدم إلى معرفته و / أو القيام به.
إذا كان هناك العديد من الحلول:
في مثل هذه الحالات ، قم بوصف كل طريقة باستخدام الرموز النقطية (المزيد حول هذا في الجزء الثاني من النصائح). إذا كانت أي طريقة معقدة ، وقد سبق أن وصفتها بالتفصيل في موضوع آخر ، فما عليك سوى تقديم رابط.
إذا كان ما تحتاج إلى فعله موصوفًا بالفعل في مكان ما في موضوع آخر:
مجرد إعطاء رابط لهذا الموضوع.
إذا لم يكن هناك تعليمات محددة ، فما الذي يمكن عمله لحل المشكلة:
قدم أي معلومات إضافية قد تساعد المستخدم على معرفة ما يمكن أن يسبب المشكلة.
الخلاصة (outro)في الختام ، يمكنك تقديم معلومات إضافية تتعلق بالمهمة أو الحلول الممكنة للمشكلة. يمكنك قراءة المزيد حول استخدام outro في
الجزء الثاني من النصائح .
استخدام الرسومات (لقطات ، مخططات ، رسوم بيانية ، إلخ.)يمكن أن تساعد لقطات الشاشة والرسوم البيانية المستخدمين على فهم أفضل لما هو مكتوب في الموضوع.
متى تستخدم الرسومات:
تحت كل خطوة ، لن تحتاج إلى إدراج لقطة شاشة - فلن يعرف المستخدم ببساطة المكان الذي سينظر إليه ، فقم بمقارنة الشاشة ولقطة الشاشة باستمرار.
يجب إدراج لقطات الشاشة عندما تساعد بشكل كبير على فهم ما هو مكتوب في التعليمات.
على سبيل المثال:
- عندما تحتاج إلى إظهار زر أو رمز ليس له اسم في gua ، أو لا يصيب العين على الفور ، أو هناك العديد من الأزرار المشابهة على الشاشة ؛
- عندما تحتاج إلى تقديم سياق للمهمة أو شرح مرئي واضح لكيفية وكيف ستبدو في النهاية ؛
- إذا كانت لقطة الشاشة تسمح لك بفهم أو شرح شيء يتطلب شرحًا طويلًا ومعقدًا في الكلمات.
أين وكيف وضع الجدول الزمني:فيما يلي بعض التوصيات حول مكان وكيفية وضع الرسومات على الصفحة.
1) إذا كانت لقطة الشاشة تعكس المعلومات المفاهيمية أو نتيجة المهمة ، فيمكنك إدراجها في المقدمة أو بعد المقدمة.
فيما يلي مثال من الوثائق الإنجليزية ، التي تعرض موضوعًا يصف وضع إطارات النوافذ. لقطة شاشة توضح ما سيحدث بعد إدخال هذا المفتاح بعد المقدمة وقبل التعليمات نفسها ، كيفية التبديل إلى هذا الوضع:
2) إذا كانت لقطة الشاشة تشير إلى خطوة محددة في التعليمات ، فقم بإدخالها بعد هذه الخطوة أو بداخلها:
إذا كنت بحاجة إلى إدراج لقطة شاشة لزر أو رمز أو عنصر واجهة آخر ، فأنت بحاجة إلى إدراجه بعد اسم هذا العنصر:
لا تستخدم الرسومات لتوضيح الأشياء الواضحة.على وجه التحديد ، لا تستخدم لقطات الشاشة لتوضيح:
- قائمة الطعام
- الرموز والأزرار وعلامات التبويب التي لها اسم
- كل شيء آخر يمكن وصفه بسهولة وسهولة في الكلمات.
نصائح إضافية لأولئك الذين يكتبون الوثائق باللغة الإنجليزية:
1)
كيفية الاستفادة من العناوين:الحروف الكبيرة تتوفر ثلاثة أنماط من الأحرف الكبيرة: نمط الجملة ونمط العنوان وكل الحروف الكبيرة.
- الكتابة بالأحرف الكبيرة للأحرف الكبيرة: يقدم هذا السطر مثالًا على الكتابة بالأحرف الكبيرة للأحرف الكبيرة.
- كتابة الأحرف الكبيرة على نمط العنوان: يقدم هذا الخط مثالاً على استخدام الأحرف الكبيرة في نمط العنوان.
- جميع الأحرف الاستهلالية: يقدم هذا السطر مثالاً على جميع الأحرف الاستهلالية.
لا تستخدم جميع القبعات للتأكيد.
الحروف الكبيرة (نمط الجملة): عند استخدام الحروف الكبيرة على غرار الجملة ، قم بتكبير الحرف الأول من الكلمة الأولى ، وكذلك الحرف الأول من أي أسماء مناسبة والصفات المناسبة.
الكتابة بالأحرف الكبيرة (نمط العنوان): استخدم الكتابة بالأحرف الكبيرة لعناوين الكتب وعناوين الأجزاء وعناوين الفصول وعناوين الأقسام (رؤوس النص).
اتبع هذه القواعد عند استخدام الحروف الكبيرة لنمط العنوان. تكبير كل كلمة باستثناء:
- المقالات (أ ، و ،) ، ما لم يكن المقال هو الكلمة الأولى أو يتبع النقطتين
- تنسيق الاقتران (و ، ولكن ، أو ، ولا ، لأجل ، بعد ، وهكذا)
- الكلمة إلى في infinitives (كيفية توصيل الطابعة)
- الكلمة كما ، بغض النظر عن جزء من الكلام
- الكلمات التي تبدأ دائمًا بحرف صغير ، مثل iPhone و iPad.
- حروف الجر المكونة من أربعة أحرف أو أقل (في ، بواسطة ، من ، إلى ، من ، إلى ، من ، إيقاف ، على ، إلى ، فوق ، فوق ، إلى ، أعلى ، ومع) ، إلا عندما تكون الكلمة جزءًا من عبارة فعل. على سبيل المثال:
بدء تشغيل أعلى ComputerLog
في ServerGet
بدأت مع المتوازي سطح المكتب
الكتابة بالأحرف الكبيرة:
• الكلمة الأولى والأخيرة ، بغض النظر عن جزء الكلام:
لمستخدمي لينكس
ما هي الأدوات المتوازية
• الكلمة الثانية في المركب الواصل:
صحيح: الأحداث الرفيعة المستوى ، معالجة 32 بت
غير صحيح: أحداث عالية المستوى ، عنونة 32 بت
استثناءات: المدمج في ، المكونات في
• الكلمات هي ، إذا ، هي ، هي ، من ، أن ، وهذا
2) كيفية استخدام كلمة "انقر":انقر فوق استخدام انقر لوصف فعل وضع المؤشر على كائن على الشاشة والضغط لفترة وجيزة على زر الماوس وتحريره. لا تستخدم الضغط على. لأن معظم المستخدمين يعرفون ماهية النقر ، تحتاج إلى تعريفه فقط في الوثائق المصممة لبدء المستخدمين ، مثل البرامج التعليمية.
صحيح: انقر فوق Mac إذا كنت تريد استخدام جهاز USB مع Mac OS X.
غير صحيح: أشر إلى Mac وانقر فوقه إذا كنت تريد استخدام جهاز USB في Mac OS X.
انقر فوق لا تستخدم استخدام نقرة.
3) البريد الإلكتروني أو البريد الإلكتروني؟استخدام البريد الإلكتروني. لا تستخدم البريد الإلكتروني.
4) إذا أم لا؟استخدم إذا للتعبير عن حالة. استخدم سواء للتعبير عن البدائل.
صحيح: تحقق من تثبيت أدوات Parallels.
غير صحيح: تحقق من تثبيت أدوات Parallels.
صحيح: انقر فوق Mac إذا كنت تريد استخدام جهاز USB مع Mac OS X.
5) كيفية استخدام أسماء المنتجات:اتبع أسلوب الكتابة بالأحرف الكبيرة على عبوة المنتج. استخدم اسم المنتج الكامل لتواجده الأول داخل قسم من النص (على سبيل المثال ، فصل). بعد ذلك ، عند الاقتضاء ، استخدم نسخة مختصرة من اسم المنتج.
على سبيل المثال: Parallels Desktop 14 for Mac: عند التواجد الأول داخل قسم من النص ، استخدم Parallels Desktop 14 for Mac.
في الأحداث اللاحقة ، استخدم سطح المكتب المتوازي.
استنتاجفي هذه الأجزاء الثلاثة من الدليل ، حاولنا أن نجمع ونلخص ونصمم النصائح التي ستساعد في جعل وثائقك أسهل وأكثر قابلية للفهم.
نحن لا نصر على أن الكتابة ضرورية بهذه الطريقة - فهناك طرق عديدة للتوثيق والتقنيات. انظر إلى الإعداد واستخدم الإعدادات التي تناسبك.
شكرا جزيلا على اهتمامك واهتمامك!