ما هي أفضل طريقة لتخزين البرامج الوثائق ؟ [مغلقة]

Question

إجابة واضحة هو "داخلي ويكي".ما هي إيجابيات وسلبيات ويكي المستخدمة في البرامج الوثائق ؟ أي اقتراحات أخرى ؟ لماذا تستخدم برنامج الوثائق ؟

لورين سيغال - للأسف ليس لدينا دعم أي دكتور أداة لجمع المعلومات من المصدر تعليقات التعليمات البرمجية ولكن أنا أتفق سيكون أفضل طريقة لتخزين الوثائق التقنية.سؤالي كان عن كل نوع من الوثائق ثو - من مسؤول النظام sysadmin نوع إلى وثائق المستخدم.

Answer 1

أن فتح باب العضوية السؤال يعتمد على العديد من العوامل.

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

إذا لم يكن لديك جيدة doc أداة دعم أو لم يكن لديك الوصول إلى شفرة المصدر ، ويكي ليست فكرة سيئة, لكنهم الخيار الثاني أعلاه.

ملاحظة:أنا أتحدث فقط عن وثائق التعليمات البرمجية هنا.غيرها من القطع الأثرية من الواضح أنه لا يمكن تخزينها جنبا إلى جنب مع كود-ويكي هو مكان رائع لوضع تلك الوثائق.بدلا من ذلك إذا كنت تستخدم بعض CMS يمكنك ببساطة ارتكابها في بعض docs/ المجلد مثل النص/pdf/مهما ملفات قابلة للتحرير عن طريق مستودع.وقد البقاء مع مستودع إذا كان يتم نقلها في حين ويكي ليس (بالضرورة).

Answer 2

أدوات مهمة, ولكن لا تحصل أيضا متورطة في العثور على أداة سحرية.لا أداة لقد وجدت حتى الآن لديه "وثيقة كل شيء سحرية باستخدام صغيرة غير مرئية الجان" tickbox.:-)

ويكي سوف تعمل بشكل جيد.أو Sharepoint.أو محرر مستندات Google.أو يمكنك استخدام SVN مستودع.الجحيم هل يمكن أن تفعل ذلك مع الأقلام ، اوراق ، و خزائن الملفات إذا كنت حقا حقا.(أنا حقا لا ننصح!)

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

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

أما عن أدوات...أنصح التقاء قبل Atlassian.انها غرامة ويكي, انها مصممة للعمل في بيئة مؤسسة ، انها لديها الكثير من الميزات أنيق ، هو للتخصيص ، وهو يدمج بشكل جيد مع بعض Atlassian الأخرى أنيق الأدوات, و هو أساسا متينا جدا المنتج.

Answer 3

"وثائق برنامج" هو مصطلح عام.هناك "End وثائق المستخدم", "وثائق المطور", "سؤال وجواب الوثائق".أول واحد هو عادة ما وضعت من قبل مؤهلين techwriters.البعض منها قد يكون حيوي تشكلت من الويكي ، الوثائق تعليقات التعليمات البرمجية المصدر.... الخكل هذه الأشياء عملية الصيانة عادة ما تكون معقدة جدا و كل شركة البرمجيات تتبع بطريقتها الخاصة.لكن هناك نقطة ضرورية لجميع هذه الطرق:كل رمز commiter, مهندس, مدير, qa engineer يجب تخزين كذلك ترتيب كل قطعة من المعلومات التي قد تكون مفيدة للآخرين.و شخص آخر يجب إبقاء العين على هذه القطع تخزين و ترتيب القطع إذا لزم الأمر.كل هذه الخطوات كثيرا تحسين جميع الأنشطة ذات الصلة في عملية التنمية.

Answer 4

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

جافادوك أو DOxygen هو أكثر ملاءمة إذا كنت تريد وثائق التعليمات البرمجية القابلة للتوزيع.

إذا كنت تشير إلى وثائق المستخدم, قد ترغب في إلقاء نظرة على ديتا.

Answer 5

بدأت تجريب طريقة للقيام وثائق المستخدم مع هذه الأهداف:

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

المستند المصدر هو مكتوب في تخفيض السعر و المقدمة إلى Html عن طريق جافا سكريبت في المتصفح وقت التشغيل.

Mandown  -  http://wittman.org/mandown/

Answer 6

نحن نستخدم حاليا وثائق مضمنة تحليل عن طريق تطبيق خارجي (PHP + PhpDocumenter) بالإضافة إلى العديد الداخلية الويكي.في بعض الأحيان انها مؤلمة في أحسن الأحوال (أساسا بسبب شخص واحد فقط تحديث الويكي أو مستندات...)

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

Answer 7

تستخدم الشركة مجموعة متنوعة من Sharepoint ويكي.Sharepoint على وثائق محددة مثل متطلبات العروض التقديمية ، العقود ، إلخ ، في حين ويكي يتم استخدام دليل المساعدة مطور مستودع الدروس على استخدام داخليا تطوير المكتبات.

Answer 8

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