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