كتاب تمهيدي عن كتابة التوثيق الجيد

ساهم المؤلف الضيف جيف ماتسون في هذا المنشور. جيف هو رئيس قسم التوثيق في GravityForms. وهو مبتكر المكون الإضافي Heartbeat Control WordPress وهو معجب بالتسعينيات.

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

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

التوثيق الجيد هو أكثر من مجرد كلمات

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

وثائق الجودة تستهدف المستخدمين الأكثر احتمالية لقراءتها. كما أنه يوفر نقطة مرجعية لأولئك الذين من غير المرجح أن يقرؤوها. على سبيل المثال ، في حالة توثيق خطاف معين ، يُفترض عادةً أن المطور سيقرأه ، ولكن ماذا عن أولئك الذين لديهم خبرة تطوير قليلة؟

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

التوثيق له تأثير أكبر مما تعتقد

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

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

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

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

هل سبق لك أن تركت عالياً وجافًا بعد إنفاق الأموال التي كسبتها بشق الأنفس وسرعان ما ندمت على الشراء؟ أعتقد أننا جميعا لدينا. من خلال التوثيق المناسب ، يمكنك تجنب نقل هذا الشعور إلى عملائك.

كيف يمكنك كتابة وثائق أفضل؟

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

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

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

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

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

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

فن الكتابة أفضل التوثيق

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

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

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

ما تعلمناه

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

آمل أيضًا أن تخرج من هذه المقالة وتفكر أكثر في وثائقك الحالية وكيف يمكن تحسينها. يمكن أن يكون التوثيق المناسب مفيدًا للغاية ، وبمجرد الممارسة ، يمكن أن يكون في الواقع ممتعًا جدًا للكتابة.

توثيق مبكرًا ، وثق كثيرًا. المنتج الرائع هو أكثر من مجرد كود رائع ، إنه أيضًا موثق بشكل جميل.