مع كل الأعمال التي ينطوي عليها إنشاء المشروع والحفاظ عليه ، يمكن في بعض الأحيان أن تنزلق الوثائق عبر الشقوق. ومع ذلك ، فإن المستندات الجيدة هي أحد الأصول الضخمة لأي مشروع. النظر في الفوائد:
- تعاون أفضل: الوثائق الواضحة والمتسقة تضمن للجميع على نفس الصفحة ، من فريقك المباشر إلى أصحاب المصلحة الخارجيين. بالإضافة إلى ذلك ، تعزز المستندات حل المشكلات المستقلة ، وتوفير المساهمين الأساسيين الوقت والجهد للإجابة على كل سؤال.
- أكثر سلاسة على متن الطائرة: من خلال توفير طرق للبدء ، وشرح المفاهيم الأساسية ، بما في ذلك المحتوى على غرار البرنامج التعليمي ، تتيح الوثائق الجيدة أعضاء الفريق الجدد للارتداد بسرعة.
- زيادة التبني: كلما كان من الأسهل فهمه وإعداده وتشغيله ، كلما زاد احتمال استخدامه شخص ما.
مع وضع هذه الفوائد في الاعتبار ، دعونا نلقي نظرة على بعض المبادئ المهمة للتوثيق ، ثم الغوص في كيفية إنشاء مستندات فعالة بسرعة لمشروعك.
المبادئ الرئيسية للوثائق
هناك ثلاثة مبادئ رئيسية يجب أن تتبعها أثناء توثيق مشروعك.
تبقيه واضحا
استخدم لغة بسيطة يسهل فهمها. الهدف من ذلك هو جعل الوثائق الخاصة بك متاحًا قدر الإمكان. يتمثل المبدأ التوجيهي الجيد في أن تسأل نفسك عما إذا كان هناك أي اختصارات أو مصطلحات تقنية في وثائقك التي لن يفهمها بعض الأشخاص في جمهورك المستهدف. إذا كان هذا هو الحال ، إما تبديلها للغة الأكثر بساطة ، أو تأكد من تعريفها في المستند الخاص بك.
اجعلها موجزة
توثيق المعلومات اللازمة فقط. إن محاولة تغطية كل حالة حافة ممكنة سوف تطغى على قرائك. بدلاً من ذلك ، اكتب مستندات تساعد الغالبية العظمى من القراء على البدء ، وفهم المفاهيم الأساسية ، واستخدام مشروعك.
بالإضافة إلى ذلك ، احتفظ بكل مستند يركز على موضوع أو مهمة معينة. إذا وجدت نفسك بما في ذلك المعلومات غير الضرورية بدقة ، فانتقل إلى مستندات منفصلة وأصغر وربطها عندما تكون مفيدة.
تبقيه منظمًا
ضع في اعتبارك بنية كل مستند أثناء كتابتك للتأكد من أنه من السهل مسحها وفهمها:
- ضع أهم المعلومات أولاً لمساعدة القراء على فهم ما إذا كانت الوثيقة ذات صلة بهم.
- استخدم العناوين وجدول المحتويات لإخبار القراء بمكان العثور على معلومات محددة. نقترح استخدام قوالب الوثائق بعناوين مشتركة لإنشاء محتوى منظم بسرعة وبشكل ثابت.
- استخدم تسليط الضوء على النص مثل Boldface وعناصر التنسيق مثل القوائم المصقولة لمساعدة القراء على مسح المحتوى. تهدف إلى تسليط الضوء على 10 ٪ أو أقل لتسليط الضوء على النص للتأكد من التأكيد على أن النص يبرز.
- كن متسقًا مع التصميم الخاص بك. على سبيل المثال ، إذا وضعت المصطلحات المهمة بالخط العريض في مستند واحد ، فافعل نفس الشيء في المحتوى الآخر.
تنظيم الوثائق الخاصة بك
مثلما تكون هناك مبادئ يجب متابعتها عند كتابة المستندات الفردية ، يجب عليك أيضًا اتباع إطار لتنظيم المستندات في ريبو الخاص بك.
هناك العديد من الأساليب لتنظيم الوثائق في ريبو الخاص بك ، ولكنها استخدمناها في العديد من المشاريع والتوصية بها إطار diátaxis. هذا نهج منهجي لتنظيم جميع المستندات ذات الصلة بمشروعك.
يمكن أن يسهل تطبيق نهج منهجي لتوثيق مستودعاتك أن يسهل على المستخدمين معرفة أين يذهبون للعثور على المعلومات التي يحتاجون إليها. هذا يقلل من الإحباط ويجعل الناس يساهمون في مشروعك بشكل أسرع.
يقسم Diátaxis المستندات بناءً على الغرض منها إلى أربع فئات:
- دروس: الوثائق الموجهة نحو التعلم
- إرشادات: تعليمات موجهة نحو الهدف لمهام محددة
- توضيح: المناقشات التي توفر فهم المشروع
- مرجع: المواصفات الفنية والمعلومات
يجب أن يتناسب كل مستند في مستودعك مع إحدى هذه الفئات. يساعد هذا المستخدمين في العثور على المورد المناسب لموقفهم الحالي ، سواء كانوا بحاجة إلى تعلم مفهوم جديد ، أو حل مشكلة محددة ، أو فهم المبادئ الأساسية ، أو البحث عن التفاصيل الفنية.
يمكن أن يكون هذا أيضًا دليلًا مفيدًا لتحديد الوثائق التي يفقدها مستودعك. هل هناك أداة يستخدم مستودعك لا يحتوي على مستند مرجعي؟ هل هناك ما يكفي من البرامج التعليمية للمساهمين للبدء في مستودعك؟ هل هناك أدلة إرشادية لشرح بعض المهام الشائعة التي تحتاج إلى إنجازها في مستودعك؟
يساعد تنظيم وثائقك وفقًا لهذا الإطار على ضمان اتباع نهج كلي لبناء المحتوى الرئيسي والحفاظ عليه لمشروعك.
كتبه
اترك تعليقاً