نصائح لكتابة الوثائق الفنية بكفاءة للمستخدمين.
الجزء 1
في مقالة سابقة ، أوضحنا كيف تتم عملية
توثيق المنتجات وتوطينها.
هذه المرة ، تحت القصاص ، هو دليل
للكاتب الفني لدينا Andrei Starovoitov ، والذي سيساعد في جعل مستنداتك أسهل وأكثر قابلية للفهم للمستخدمين (يتم استخدام التقنيات الموضحة من قِبل Apple و Microsoft وشركات أخرى لتوثيق منتجاتهم).
كما تعلمون ، فإن التوثيق الجيد ليس ترفًا ، ولكنه وسيلة لزيادة مبيعات الشركة. إذا كنت ستبدأ أو كنت بصدد تطوير نوع من البرامج بالفعل ، ثم للدخول إلى السوق العالمية به ، ستحتاج إلى دليل مستخدم (ويعرف أيضًا باسم دليل المستخدم) أو على الأقل وثيقة تخبر العملاء بكيفية البدء في العمل مع منتجك (ما يسمى بـ الابتداء مع).
في أي لغة لكتابة الوثائق - باللغة الروسية ، ومن ثم ترجمتها ، أو على الفور باللغة الإنجليزية - عليك أن تقرر. في Parallels ، اخترنا النهج الثاني. غالبًا ما يكون وضع وصف باللغة الإنجليزية أسهل كثيرًا ، حيث يتم استعارة جميع مصطلحات الكمبيوتر "كلها" (الروسية) تقريبًا (والآن يمكننا أن نقول ذلك).
كذلك في النص ، سوف نركز على كل من الأمثلة الروسية والإنجليزية.
إذن ما الذي يجب أن تبحث عنه عند كتابة الوثائق؟
أنواع المواضيع في الوثائق
عند كتابة موضوع ، تحتاج أولاً إلى تحديد نوع الموضوع الذي سيكون :)
من هذا سيعتمد على ماذا وكيف تكتب فيه.
هناك
4 أنواع رئيسية من الموضوعات :
•
الموضوعات التي تصف كيفية حل مشكلة معينة أو عدة مهام ذات صلة (يُسمى هذا النوع من
الصفحات صفحات المهام باللغة الإنجليزية
) .
على سبيل المثال ، "تثبيت سطح المكتب المتوازي" أو "إيقاف تشغيل أو إيقاف تشغيل Windows مؤقتًا". يصف كل موضوع من هذه الموضوعات سلسلة من خطوة واحدة أو أكثر يجب على المستخدم اتخاذها لتحقيق هدف محدد. دليل المستخدم يتكون أساسا من هذه المواضيع.
عادةً لا يحب المستخدمون القراءة ، خاصةً عندما يكون هناك الكثير من النص. لذلك ، يجب أن تحاول جعل مثل هذه المواضيع قصيرة قدر الإمكان. من الناحية المثالية ، إذا تم تقديم المعلومات في النموذج التالي: "يمكنك القيام بشيء ما ، ما عليك سوى النقر هنا وهنا" (ستتم مناقشة مواضيع المهمة بمزيد من التفاصيل في الجزء التالي من المقالة).
إذا اعتقد المطور أن هناك أي معلومات إضافية يحتاج المستخدم إلى معرفتها ، وهناك الكثير منها ، فمن الأفضل وصفها في الموضوعات المفاهيمية (انظر أدناه).
•
الموضوعات المفاهيمية (باللغة الإنجليزية -
صفحات المفاهيم ). في هذه المواضيع لا توجد تعليمات حول كيفية حل أي مشكلة. أنها تحتوي على معلومات تساهم بدلاً من ذلك في زيادة فهم الأشياء. على سبيل المثال ، يتم استخدام الموضوعات المفاهيمية من أجل:
- وضح للمستخدمين بالضبط كيف تعمل أي عملية ؛
- معرفة ما يمكن القيام به في إعدادات التطبيق ؛
- وصف الميزات المضافة في الإصدار الجديد من المنتج ؛
- تقديم معلومات إضافية تساعد المستخدم على فهم المشكلة أو حلها بشكل أفضل.
يرجى ملاحظة أن المعلومات الإضافية (في حالة وجود الكثير منها) يجب تقديمها بدقة في الموضوع المفاهيمي حتى لا تفرط في تحميل موضوع المهمة.
•
مواضيع التعليمات (باللغة الإنجليزية -
الصفحات المرجعية ) - تحتوي على معلومات يمكن للمستخدم الرجوع إليها بشكل دوري لمعرفة معنى مصطلح معين ، وكيف تعمل الوظيفة ، إلخ. وخير مثال على هذه المواضيع هو القاموس في نهاية الدليل (الملقب Glossary). تعد الموضوعات المرجعية مفيدة بشكل خاص لشرح الغرض من عناصر الواجهة المختلفة.
•
الموضوعات التي تصف كيفية حل مشكلة (باللغة الإنجليزية -
صفحات استكشاف الأخطاء وإصلاحها ).
على سبيل المثال: "لا يمكنني تنشيط Parallels Desktop" أو "لا يمكنني الاتصال بالإنترنت". تصف هذه المواضيع ما يجب القيام به لحل مشكلة ما. قد تحتوي أيضًا على معلومات تساعد على فهم سبب عطل الجهاز.
التعليمات الأساسية لجميع أنواع الوثائق
عند إنشاء دليل:
1)
التركيز على المستخدم
• بدلاً من هيكلة وصف المنتج على ميزاته أو عناصر الواجهة ، حاول التركيز على المهام التي من المحتمل أن يحاول المستخدم حلها.
على سبيل المثال ، يمكن تسمية موضوع حول كيفية حماية البيانات في جهاز ظاهري بطريقتين:
أ) "إعدادات الأمان" ، التي تصف بالتفصيل ما يمكن القيام به لحماية البيانات.
ب) اجعل عدة مواضيع تصف مهام محددة:
- "حماية بياناتك باستخدام برنامج مكافحة الفيروسات"
- "نسخ احتياطي لجهازك الافتراضي" ("نسخ احتياطي لجهازك الافتراضي")
وفقًا للاتجاهات الحالية في الوثائق ، فإن الطريقة الثانية هي الأفضل ، لأنه في هذه الحالة لا يتعين على المستخدم تخمين ما إذا كان يجب القيام بشيء ما أم لا ، ويتلقى تعليمات واضحة بشأن ما يجب القيام به بالضبط.
• التركيز على مهام المستخدم ومستوى محو الأمية التقنية.
على سبيل المثال ، في وثائق المستخدم العادي ، بدلاً من كتابة "إنشاء جهاز ظاهري" ، يجب أن تكتب "تثبيت Windows أو أي نظام تشغيل آخر" ، مثل المصطلح " آلة افتراضية "ليست معروفة للجميع. أو مثال آخر - موضوع يصف كيفية إنشاء اختصارات لوحة المفاتيح السريعة ، من الأفضل استدعاء "تكوين اختصارات لوحة المفاتيح" بدلاً من "إعدادات لوحة المفاتيح".
على الرغم من أن هذه هي النقطة المهمة ، إلا أنه بالنسبة لغالبية قراء هابر ، سيكون من الواضح "تكوين الاختصارات" ، لكن السؤال يدور حول مدى ملاءمة هذا المصطلح في المصطلحات الرسمية في هذا الوقت :)
• إذا لم يكن ذلك واضحًا ، فسر سبب احتياج المستخدم لأداء مهمة معينة.
على سبيل المثال:
• عند الوصف ، حاول استخدام تلك الكلمات التي يستخدمها المستخدم كل يوم في خطابه. إذا كان يمكن استبدال مصطلح معقد تقنيًا بكلمات أبسط ، فحاول دائمًا استخدام كلمات أبسط.
على سبيل المثال ، "شفاف" بدلاً من "شفاف". إذا أعطيت مثالًا من اللغة الإنجليزية ، فاستخدم "use" بدلاً من "use".
2)
حاول إعطاء جميع المعلومات اللازمة دون كلمات غير ضروريةجاء سفراء من جزيرة ساموس إلى سبارتا لطلب المساعدة. لقد ألقوا كلمة طويلة وجميلة. قال الأسبرطيون: "بعد الاستماع إلى النهاية ، نسينا البداية ، ونسيان البداية ، لم نفهم النهاية". كانت Samosets سريعة البديهة. في اليوم التالي ، جاءوا إلى الاجتماع بحقيبة فارغة وقالوا أربع كلمات فقط: "هناك حقيبة ، لا يوجد دقيق". وبخهم سبرتنس - كلمتين كانتا كافيتين: "لا يوجد دقيق" ، لكنهم كانوا سعداء بهذه الذكاء السريع ووعدوا بالمساعدة ".إذا وصفت الوظيفة لفترة طويلة - لن يقرأها أحد. لكن الأمر "تمامًا في Spartan" أيضًا ، لأنه إذا تم كتابة القليل من الأسئلة ، فستكون هناك أسئلة وشكوك ، سيبدأ المستخدمون في سحب فريق الدعم. بشكل عام ، من المهم الحفاظ على التوازن.
لمساعدة المستخدمين في العثور على جميع المعلومات التي يحتاجون إليها ، وفي نفس الوقت يصف كل قسم بإيجاز قدر الإمكان:
- ركز على أهم المعلومات اللازمة لحل المشكلة الموضحة في الموضوع. إذا كانت بعض التفاصيل غير ضرورية للمهمة ، فلا تصفها.
- لا حاجة لتوثيق كل نقرة. إذا كان كل شيء واضحًا في الواجهة ، فدع المستخدم يكتشف نفسه بنفسه. على سبيل المثال ، بدلاً من توثيق كل خطوة من خطوات تثبيت البرنامج ، من الأفضل أن تكتب: "من أجل تثبيت البرنامج ، اتبع الإرشادات التي تظهر على الشاشة." إذا كان عليك ، في المرحلة الأخيرة من الإجراء ، النقر فوق "موافق" ، فإن هذا لا يستحق أيضًا الوصف.
- بدلاً من إعطاء جميع المعلومات في موضوع واحد ، أظهر للمستخدم حيث يمكنك قراءة معلومات إضافية باستخدام روابط لموضوعات أخرى ، أو روابط إلى موارد خارجية ، أو إدراج في النهاية قسم "المعلومات ذات الصلة" ، والذي سيحتوي على روابط إلى الموضوعات المتعلقة بما هو موضح على الشاشة.
- إذا كان يمكن تقسيم مهمة طويلة إلى عدة مراحل أو مهام فرعية ، كل منها مهمة منفصلة ، فقم بتقسيم الموضوع إلى أقسام مناسبة أو إنشاء قسم في الدليل ، يتكون من مواضيع تصف كل مرحلة. في هذه الحالة ، لا تنس إدراج روابط لموضوعات ذات صلة.
- إذا كان من الممكن تنفيذ مهمة (على سبيل المثال ، بدء تشغيل جهاز افتراضي) بعدة طرق ، فليست هناك حاجة لوصفها جميعًا. يكفي أن أذكر الطريقة الأسرع والأسهل. إذا كنت لا تزال تعتقد أنه من المفيد للمستخدم معرفة أي طريقة أخرى ، فقم بوصفها في الموضوع (بالإنجليزية - Outro).
3)
لا تكرر نفس المعلومات على الصفحات
بدلاً من تكرار المعلومات في كل موضوع تم وصفه بالفعل في بعض الموضوعات الأخرى ، من الأفضل الإشارة إلى أنه يمكن العثور على وصف أكثر تفصيلًا في مثل هذا الموضوع ، أو مجرد تقديم رابط تشعبي إليه.
4)
جذب انتباه المستخدم بشكل صحيح
عندما يحتاج الوصف إلى جذب انتباه المستخدم ، يتم استخدام الكلمات التمهيدية التالية - "انتباه!" (باللغة الإنجليزية - تحذير!) ، "هام:" (باللغة الإنجليزية - مهم :) و "ملاحظة:" (باللغة الإنجليزية - ملاحظة :).
كل هذه الكلمات تعني مستوى "الأهمية" الخاص بها.
من أجل عدم إجهاد المستخدم عبثا ، استخدم كل مصطلح بشكل صحيح:
- انتبه! (تحذير! باللغة الإنجليزية) للإشارة إلى موقف خطير والذي ، إن لم يتم تجنبه ، قد يؤدي إلى فقد البيانات أو تلف المكون أو أي ضرر آخر.
- استخدم "هام:" (باللغة الإنجليزية - هام :) للإشارة إلى موقف كبير يحتمل أن يكون إشكاليًا ، ومع ذلك ، لا يمكن أن يؤدي ذلك إلى تلف مادي أو تلف أو فقدان البيانات.
- استخدم "ملاحظة:" (ملاحظة :) لتقديم أي معلومات إضافية تتعلق بهذا الموضوع. على الرغم من أن هذا الإدراج يفصل المستخدمين عن المهمة الحالية ، إلا أنه قد يكون مفيدًا.
على سبيل المثال:
لفتح تكوين الجهاز الظاهري ، انقر فوق تصرفات> تكوين.
ملاحظة: يجب إيقاف تشغيل الجهاز الظاهري.
استخدم الملاحظة "ملاحظة:" بشكل ضئيل - إذا قمت بإدراجه كثيرًا ، فإنه يسد النص ويتوقف عن الانتباه إليه.
إذا كان ذلك ممكنًا ، فقم بإدراج "انتباه!" و "هام:" و "ملاحظة:" في بداية الموضوع حتى يكتشف المستخدم ذلك قبل البدء في تنفيذ أي إجراء. ومع ذلك ، إذا كانت المعلومات تشير فقط إلى خطوة معينة ، فأدخلها بعد هذه الخطوة.
مثال:
أن تستمر ...(في الجزء التالي من المقالة سنناقش بمزيد من التفصيل موضوعات تصف كيفية حل مشكلة معينة)