قائمة التحقق من وثائق البيئة [مغلق

Question

أنا أعمل في شركة تأمين. لدينا قسم التنمية الخاصة بنا المصنوع من ما يقرب من 150 شخص بالإضافة إلى بعض مقدمي الخدمات (الاستعانة بمصادر خارجية وتطبيقات حسب الطلب إلى حد كبير). في شركتنا جعل فريقي ما نسميه مكتبات منطق غير وظيفية. هذا هو، مكتبات البرمجيات للتعامل مع الأشياء الأفقية لجميع فرق التطوير في قسمنا، مثل الأمن، والخدمات الإضافية، والتسجيل، والرسائل وما إلى ذلك. معظم هذه الأدوات أو هذه الأدوات إما مصنوعة من نقطة الصفر أو تكييف معيار De-Facto. على سبيل المثال مسجلنا هو applender بناء على log4j يحفظ أيضا رسائل التسجيل في DB. نحدد أيضا المكتبات التي تستخدمها في التطبيق، على سبيل المثال أي إطار من الخدمات لاستخدامها عبر الإنترنت. نستخدم الكثير من Javaee و Oracle كما هو الحال في جميع منظمتنا (مع بعض خوادم تطبيق WebSphere).

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

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

شيء يأتي إلى ذهني:

1. دليل API المرجعي
2. بدء تشغيل البرنامج التعليمي
3. واجهة برمجة التطبيقات التي أنشأت الوثائق.
4. يجب أن يكون البحث
5. وصول الويب

ماذا يجب أن يكون لديك؟ أيضا، في تجربتك ما هي أفضل طريقة للحفاظ عليها (احتفظ بها محدثة) ونشر هذا النوع من الوثائق؟

Answer 1

حافظ على وثائقك في عنصر تحكم الإصدار أيضا.

تأكد من كل صفحة له رقم إصدار حتى تعرف من أين كان المستخدم قد قرأ من.

احصل على خادم CI يسير وضفع الوثائق إلى موقع وثائق LIVE عند التحديثات.

هل مراجعات المستندات، كما ستتم الاستعراضات رمز.

الكلب الغذاء ذلك :)

العطف،

دان