وثائق البرنامج هي مجرد مجموعة من المقالات ، ولكن حتى يمكن أن تجعلك مجنونًا. أولاً ، تبحث عن التعليمات الصحيحة لفترة طويلة ، ثم تفهم النص الغامض ، افعل ما هو مكتوب ، لكن المشكلة لم تحل. كنت تبحث عن مقال آخر ، فأنت متوتر ... بعد ساعة من البصق على كل شيء وتركته. هذه هي الطريقة التي تعمل وثائق سيئة. ما الذي يجعلها كذلك ، وكيفية إصلاحها - قراءة تحت الخفض.
وثائقنا القديمة كان بها الكثير من العيوب. منذ عام تقريبًا ، نقوم بمعالجته حتى لا يتعلق السيناريو الموصوف أعلاه بعملائنا. انظر كيف كان وكيف أصبح .
المشكلة 1. غير مفهومة ، ومقالات مكتوبة بشكل سيء
إذا كان من المستحيل معرفة الوثائق ، فما هي النقطة؟ لكن لا أحد يكتب مقالات غامضة عن قصد. يتم الحصول عليها عند المؤلف لا يفكر في الجمهور والغرض ، يصب الماء ولا يتحقق النص عن الأخطاء.
- الجمهور . قبل كتابة مقال ، عليك أن تفكر في مستوى إعداد القارئ. من المنطقي أنه في المقالة الخاصة بالمبتدئين ، يجب ألا تتخطى الخطوات الأساسية وتترك المصطلحات الفنية دون فك التشفير ، وفي المقال المتعلق بميزة نادرة ضرورية فقط للمحترفين ، تمضغ معنى كلمة PHP.
- الغرض . شيء آخر يجب أن تفكر فيه مسبقا. يجب على المؤلف تحديد هدف واضح وتحديد التأثير المفيد للمقال وتحديد ما سيفعله القارئ بعد قراءته. إذا لم يتم ذلك ، فسيتم الحصول على وصف من أجل الوصف.
- الماء والبق . الكثير من المعلومات غير الضرورية ورجال الدين والأخطاء والأخطاء المطبعية تتداخل مع الإدراك. حتى لو لم يكن القارئ دولة نحوية ، فإن الإهمال في النص يمكن أن يدفعه بعيدًا.
النظر في النصائح أعلاه ، وسوف تصبح المواد أكثر وضوحا - مضمونة. لجعله أفضل ، خذ
الأسئلة الخمسين عند العمل على الوثائق التقنية .
المشكلة 2. المقالات لا تجيب على جميع الأسئلة
إنه أمر سيء عندما لا تواكب الوثائق التطوير ، ولا تجيب على الأسئلة الحقيقية ، والأخطاء فيه لم يتم إصلاحها لسنوات. هذه المشكلات ليست مؤلفًا كثيرًا ، مثل تنظيم العمليات داخل الشركة.
الوثائق لا تواكب التطور
الميزة موجودة بالفعل في الإصدار ، وتخطط التسويق لتغطيتها ، وتبين أن المقالة الجديدة أو الترجمة لا تزال غير موجودة في الوثائق. لهذا السبب ، كان علينا حتى تأجيل الإصدار. يمكنك أن تطلب من الجميع تسليم المهمة إلى كتاب تقنيين في الوقت المحدد ، لكن هذا لن ينجح. إذا لم تكن العملية مؤتمتة ، فسيتم تكرار الموقف.
لقد أجرينا تغييرات على YouTrack. تقع مهمة كتابة مقال عن ميزة جديدة على عاتق الكاتب التقني في نفس الوقت الذي يبدأ فيه اختبار الفرصة. ثم يتعلم التسويق عنها من أجل الاستعداد للترقية. تأتي الإخطارات أيضًا في برنامج messenger Mattermost الخاص بالشركات ، لذلك من المستحيل تفويت أخبار المطورين.
الوثائق لا تعكس طلبات المستخدمين
اعتدنا أن نعمل مثل هذا: ظهرت ميزة ، تحدثنا عن ذلك. وصفنا كيفية تشغيله وإيقاف تشغيله وإعداد إعدادات دقيقة. ولكن ماذا لو كان العميل يستخدم برنامجنا بطريقة لم نتوقعها؟ أم أنه يرتكب أخطاء لم نفكر فيها؟
لكي تكتمل الوثائق قدر الإمكان ، ننصحك بتحليل طلبات الدعم والأسئلة في المنتديات المواضيعية والاستعلامات في محركات البحث. ينبغي نقل الموضوعات الأكثر شيوعًا إلى كتاب تقنيين لاستكمال المقالات الموجودة أو كتابة مقالات جديدة.
لا يتم تحسين الوثائق
من الصعب القيام به على الفور تمامًا ، على أي حال ستكون هناك أخطاء. يمكنك الاعتماد على تعليقات العملاء ، لكن من غير المحتمل أن يبلغوا عن كل خطأ مطبعي أو غير دقيق أو غير مفهوم أو غير معروف. بالإضافة إلى العملاء ، يقرأ الموظفون الوثائق ، مما يعني أنهم يرون نفس الأخطاء. يمكن استخدامه! من الضروري فقط تهيئة الظروف التي يسهل فيها الإبلاغ عن مشكلة.
لدينا مجموعة على البوابة الداخلية حيث يترك الموظفون التعليقات والاقتراحات والأفكار حول الوثائق. الدعم يحتاج إلى مقال لكن أليس كذلك؟ هل لاحظ المختبر عدم دقة؟ شكا شريك لمديري التنمية عن الأخطاء؟ كل شيء في هذه المجموعة! يقوم الكتّاب الفنيون بإصلاح شيء ما على الفور ، ونقل شيء إلى YouTrack ، واتخاذ شيء للتفكير فيه. للحفاظ على الموضوع هادئًا ، من وقت لآخر ، نتذكر وجود المجموعة وأهمية التعليقات.
المشكلة 3. عليك أن تبحث عن المادة المناسبة لفترة طويلة
مقالة لا يمكن العثور عليها ليست أفضل من مقالة ليست كذلك. يجب أن يكون شعار التوثيق الجيد "سهل البحث ، يسهل العثور عليه." كيف تحقق هذا؟
تبسيط الهيكل وتحديد مبدأ اختيار المواضيع . يجب أن تكون البنية شفافة بقدر الإمكان حتى لا يفكر القارئ "أين يمكنني أن أجد هذا المقال؟" لتلخيص ، هناك طريقتان: من الواجهة ومن المهام.
- من الواجهة. يكرر المحتوى أقسام اللوحة. لذلك كان في وثائق ISPsystem القديمة.
- من المهام. تعكس عناوين المقالات والأقسام مهام المستخدمين ؛ تحتوي العناوين دائمًا على أفعال وإجابات على السؤال "كيفية القيام". الآن نحن نتحرك إلى هذا التنسيق.
بغض النظر عن الطريقة التي تختارها ، تأكد من أن الموضوع يلبي احتياجات المستخدمين ويتم تغطيته حتى يتمكن المستخدم من حل سؤاله بدقة.
إنشاء بحث مركزي . في عالم مثالي ، يجب أن يعمل البحث حتى عندما تكون حزينًا أو مخطئًا مع اللغة. بحثنا في التقاء لا يمكن إرضاء هذا حتى الآن. إذا كان لديك العديد من المنتجات ، وكانت الوثائق عامة ، فاضبط البحث على الصفحة التي يوجد بها المستخدم. في حالتنا ، يعمل البحث الرئيسي على جميع المنتجات ، وإذا كنت موجودًا بالفعل في قسم معين ، فعندئذٍ فقط في المقالات الموجودة فيه.
أضف المحتوى وفتات الخبز . إنه لأمر جيد عندما تكون هناك قائمة وفتحات التصفح في كل صفحة - مسار المستخدم إلى الصفحة الحالية مع إمكانية العودة إلى أي مستوى. في وثائق ISPsystem القديمة ، كان عليك الخروج من المقالة للوصول إلى المحتوى. كان غير مريح ، لذلك في الجديد نحن إصلاحه.
ترتيب الروابط في المنتج . إذا كان الأشخاص يقدمون الدعم من وقت لآخر بنفس السؤال ، فمن المعقول إضافة تلميح مع الحل الخاص به إلى الواجهة. إذا كانت لديك بيانات أو تفهم في أي نقطة يواجه المستخدم مشكلة ، فيمكنك أيضًا إخطاره عن طريق الرسائل الإخبارية. توخي الحذر وإزالة الحمل من الدعم.
يوجد على اليمين في النافذة المنبثقة رابط لمقال حول إعداد DNSSEC في قسم إدارة مجال ISPmanagerإعداد المراجع التبادلية داخل الوثائق . المقالات المرتبطة يجب أن تكون "مرتبطة". إذا كانت المقالات تسلسلًا ، فتأكد من إضافة أسهم للأمام وللخلف في نهاية كل نص.
على الأرجح ، سيذهب الشخص أولاً لطلب إجابة عن سؤاله ، ليس لك ، ولكن لمحرك البحث. إنه لأمر مخز إذا لم تكن هناك روابط للوثائق هناك لأسباب فنية. حتى تأخذ الرعاية من محرك البحث الأمثل.
المشكلة 4. تخطيط عفا عليها الزمن يتداخل مع الإدراك
بالإضافة إلى النصوص السيئة ، قد يدمر التصميم الوثائق. اعتاد الناس على قراءة المواد جيدة الصنع. المدونات ، والشبكات الاجتماعية ، والوسائط - يتم تقديم جميع المحتويات ليس فقط جميلة ، ولكن أيضًا سهلة القراءة ، ممتعة للعين. لذلك ، يمكنك بسهولة فهم ألم الشخص الذي يرى النص كما في لقطة الشاشة أدناه.
هناك العديد من لقطات الشاشة والتحديدات في هذه المقالة التي لا تساعد ، ولكن تتداخل فقط مع الإدراك (الصورة قابلة للنقر)لا يجدر بنا أن نقف في طابور طويل مع مجموعة من التأثيرات من الوثائق ، لكن يجب عليك مراعاة القواعد الأساسية.
تخطيط . حدد عرض النص الرئيسي والخط والحجم والرؤوس والمسافات البادئة. إشراك المصمم ، وقبول وظيفة أو القيام بها بنفسك ، اقرأ كتاب "تخطيط وتخطيط" من Artyom Gorbunov. إنه يقدم واحدًا فقط من طرق العرض على التخطيط ، لكنه يكفي تمامًا.
المخصصات . تحديد ما يحتاج إلى التركيز في النص. عادةً ما يكون هذا هو المسار في الواجهة والأزرار وإدراج الرمز وملفات التكوين وكتل "الالتفات". عيّن ما سيتم اختيار هذه العناصر وحدده في الجدول. ضع في اعتبارك أن الإفراز الأقل ، كان ذلك أفضل. عندما يكون هناك الكثير منهم ، والنص "يجعل الضوضاء". حتى علامات الاقتباس تخلق ضوضاء في حالة استخدامها بكثرة.
لقطات رتب مع الفريق الذي تحتاج فيه إلى لقطات شاشة. بالتأكيد ليست هناك حاجة لتوضيح كل خطوة. وهناك عدد كبير من لقطات ، بما في ذلك أزرار الفردية تتداخل مع التصور ، وتفسد تخطيط. تحديد الحجم ، وكذلك تنسيق التحديدات والتعليقات التوضيحية في لقطات ، إصلاح في اللوائح. تذكر أن الرسوم التوضيحية يجب أن تكون مكتوبة وذات صلة دائمًا. مرة أخرى ، إذا تم تحديث المنتج بانتظام ، فسيكون من الصعب تتبع كل منتج.
طول النص . تجنب مقالات طويلة للغاية. قم بتقسيمها إلى أجزاء ، وإذا لم يكن ذلك ممكنًا ، أضف محتوى مرتبطًا بالمرساة إلى أعلى المقالة. طريقة سهلة لجعل مقالة أقصر بصريا هي إخفاء التفاصيل التقنية التي تحتاجها دائرة ضيقة من القراء تحت المفسد.
التنسيقات اجمع بين عدة صيغ في المقالات: النص والفيديو والصور. هذا سوف يحسن التصور.
لا تحاول التستر على مشاكل مع تخطيط جميل. بصراحة ، كنا نأمل بأن يحفظ "الغلاف" الوثائق القديمة - لم ينجح الأمر. كان للنصوص ضوضاء بصرية وتفاصيل غير ضرورية لدرجة أن اللوائح والتصميم الجديد كانا عاجزين.
سيتم تحديد الكثير مما سبق من خلال الموقع الذي تستخدمه للتوثيق. بالنسبة لنا ، على سبيل المثال ، هذا هو التقاء. كان عليه أيضا أن العبث بها. إذا كنت مهتمًا ، اقرأ قصة مطور الويب الخاص بنا:
التقاء لقاعدة معارف عامة: تغيير التصميم وإعداد فصل اللغة .
من أين نبدأ بالتحسن وكيف نعيش
إذا كانت مستنداتك شاسعة مثل مستندات ISPsystem ، ولا تعرف ما الذي يجب انتزاعه ، فابدأ بأخطر المشكلات. لا يفهم العملاء كيفية تحسين النصوص ووضع اللوائح وتدريب الكتاب. الوثائق قديمة - تأخذ العمليات الداخلية. ابدأ بالمقالات الأكثر شيوعًا حول المنتجات الأكثر طلبًا: اطلب الدعم ، وانظر إلى تحليلات مواقع الويب واستفسارات محركات البحث.
دعنا نقول على الفور - لن يكون الأمر سهلاً. وبسرعة ، أيضًا ، من غير المرجح أن تنجح. ما لم تكن قد بدأت للتو وتفعل على الفور. نحن نعرف شيئًا واحدًا مؤكدًا - سيتحسن مع مرور الوقت. لكن العملية لن تنتهي أبدا :-).