हम एक नए open source project को दस्तावेज करने की सोच रहे हैं, और मैं अच्छे तरीकों और औजारों पर कुछ सुझावों की उम्मीद कर रहा था जो आपके लिए अच्छा काम करते थे। इसके अलावा, एक डेवलपर के रूप में, क्या आप ऑनलाइन दस्तावेज़, विकी आधारित दस्तावेज़, फ़ाइलों की सहायता, या कुछ अन्य पसंद करते हैं?ओपन सोर्स प्रोजेक्ट के साथ दस्तावेज़ीकरण के लिए सिफारिशें?
यह देखकर कि आपका आवेदन सी # में विकसित किया जा रहा है, अपने एपीआई दस्तावेज उत्पन्न करने के लिए Doxygen पर एक नज़र डालें। यह बेहद शक्तिशाली है (यह मानक जावाडोक स्टाइल सदस्य प्रलेखन करता है, लेकिन कॉल, विरासत, फ़ाइल निर्भरता और सहयोग ग्राफ भी उत्पन्न करेगा)। इसकी शक्ति के बावजूद इसका उपयोग करना आसान है। यह असंख्य प्रारूपों में एपीआई दस्तावेज़ उत्पन्न कर सकता है: एचटीएमएल, लेटेक्स, मैनपेज, आदि
मैनुअल, ट्यूटोरियल और अन्य लचीली प्रकार के दस्तावेज लिखने के लिए गंभीरता से विकी स्थापित करने पर विचार करें। मैंने बड़ी सफलता के साथ DokuWiki का उपयोग किया है। इसे सिंटैक्स हाइलाइटिंग के लिए समर्थन मिला है, इसलिए कोड प्रोजेक्ट के लिए यह अच्छा है। इसमें उपयोगकर्ता एसीएल भी हैं जो ओपन सोर्स प्रोजेक्ट के लिए आसान होंगे। यह केवल PHP और कोई डेटाबेस की आवश्यकता है। बेशक यह मानक विकी फीचर्स जैसे वर्जनिंग प्रदान करता है।
आखिरकार, मुझे trac का उल्लेख करना चाहिए, जो एक विकी, संस्करण नियंत्रण, बग ट्रैकर हाइब्रिड है। यह निश्चित रूप से एक लायक है।
जबकि मैंने वास्तव में किसी भी ओपन सोर्स प्रोजेक्ट को प्रायोजित नहीं किया है, तो मैं जो काम करता हूं वह सहयोगी है। मैंने पाया है कि उचित अनुमतियों वाला विकी लोगों को आम दस्तावेजों को लिखने में सहयोग करने का एक शानदार तरीका है। मेरे मामले में वे आम तौर पर विकास कहानियां हैं - I और ग्राहक इन्हें उत्पन्न करने पर काम करते हैं। मुझे लगता है कि यह आपकी परियोजना के लिए सहयोगी दस्तावेज़ीकरण के साथ भी अच्छी तरह से काम करेगा।
मुझे विशेष रूप से इसके सहयोग के लिए विकी के विचार पसंद हैं। – ccook
Sandcastle जैसे लगता है आपके लिए एक अच्छा फिट होगा।
मैं जिस तरह का समर्थन करता हूं वह विकी का उपयोग है। हालांकि, मुझे स्रोत कोड से ऑटो-जनरेटिंग दस्तावेज़ों की क्षमता पसंद है। वहां बहुत सारे टूल हैं लेकिन मैं विशेष रूप से SandCastle का शौकीन हूं। यह एमएसडीएन दस्तावेज़ों पर समान स्टाइल प्रदान करता है जो अधिकांश .NET डेवलपर्स के पास पहले से ही अनुभव करने का अनुभव होना चाहिए और ऐसा लगता है कि आपका ओपन सोर्स प्रोजेक्ट .NET में बनाया गया है। जहां तक मैं देख सकता हूं, समर्थित नवीनतम ढांचा .NET 2.0 है।
ऑनलाइन दस्तावेज़ हमेशा एक अच्छा विचार होते हैं, खासकर जब विकी आधारित होता है। वे अधिक खोजे जा सकते हैं, गलतियों के मामले में कुछ इतिहास रखा जाता है, और वे आमतौर पर छोटे होते हैं क्योंकि उनके पास लंबे दस्तावेज कथा या मैनुअल की "चीनी" नहीं होती है। हालांकि, लेख नामकरण और लिंक के साथ अतिरिक्त देखभाल की जानी चाहिए।
यदि प्रोजेक्ट कोड के कुछ हिस्सों एपीआई के रूप में कार्य करते हैं, तो प्रासंगिक ज्ञान को कोड में पकड़ा जाना चाहिए ताकि यह आईडीई "कॉल पर होवर" तंत्र का उपयोग करके इसका पता लगा सके। ज्ञान का वितरण एक बड़ी समस्या है, और लोग आमतौर पर एक संदर्भ स्विच करने के लिए अनिच्छुक होते हैं। यदि फंक्शन हेडर डॉक्यूमेंटेशन में कुछ दिखाई देता है, तो यह कहीं अधिक दिखाई देता है, हालांकि इसे कहीं भी पढ़ने की संभावना अधिक है (हालांकि उच्च समग्र नहीं)।
फ़ंक्शन हेडर दस्तावेज़ लिखते समय, निर्देशों पर ध्यान केंद्रित करें - चीजें जो सीधे क्लाइंट को प्रभावित करती हैं। ये अनिवार्य हो सकते हैं (उदाहरण के लिए, पहले एक्स को कॉल करें), या जानकारीपूर्ण (उदा।, ध्यान रखें कि एक्स ...)।
देखें कि कैसे दूसरे ऐसा करें (बिग ओपनसोर्स प्रोजेक्ट्स मेरा मतलब है)
लेकिन मेरे लिए विकी (अन्य पोस्टर्स द्वारा उल्लिखित) के अलावा कुछ official दस्तावेज अलगाव है संरचनात्मक/दिशानिर्देश सामग्री के लिए आवश्यक है। विकी knowledge base सामग्री के लिए अधिक है IMHO
डेवलपर लिखित दस्तावेज़ीकरण के लिए मुझे व्यक्तिगत रूप से Sphinx पसंद है, आंशिक रूप से इसके कारण उत्पन्न दस्तावेज़ कितना अच्छा लगता है। यह ReST में लाटेक्स (प्रिंटिंग/पीडीएफ के लिए) या एचटीएमएल में लिखे दस्तावेज़ों को संसाधित करता है।
मैं केवल को एपीआई दस्तावेज उपकरण जैसे डॉक्सिजन का उपयोग करके अनुशंसा नहीं करता। यह बहुत अच्छा है अगर इसका भी उपयोग किया जाता है, लेकिन यह दस्तावेज़ीकरण का एकमात्र रूप नहीं होना चाहिए।
आपके उपयोगकर्ता समुदाय कितना सक्रिय है, इस पर निर्भर करता है कि मैं व्यंजनों या अन्य ट्यूटोरियल के लिए विकी जोड़ने की भी सिफारिश करता हूं, इसकी सामग्री को अंतराल पर स्फिंक्स द्वारा उपयोग किए जाने वाले आरएसटी दस्तावेज में जोड़ा जा सकता है।
[संभवतः महान एपीआई दस्तावेज़ीकरण: उपकरण और तकनीक] बनाना (http://stackoverflow.com/questions/2001899/creating-great-api- दस्तावेज-tools-and-techniques) – Mark
इस प्रश्न को एक वर्ष से पूछा गया था 'डुप्लिकेट' से पहले :) – ccook