लक्षित दर्शक
मुझे लगता है कि इस प्रश्न का उत्तर देते समय आपको वास्तव में यह पूछने की आवश्यकता है कि इस प्रलेखन को पढ़ने के लिए कौन है। एक डेवलपर के पास उपयोगकर्ता या यहां तक कि एक व्यापार विश्लेषक की सकल आवश्यकताएं हैं।
- एक डेवलपर के रूप में: कोड का अध्ययन किया जा रहा है, इंटरफ़ेस अनुबंध और उपयोग के उदाहरण जैसे विवरणों से जुड़ा हुआ है। शायद कुछ उच्च स्तरीय प्रलेखन, और प्रोटोकॉल अच्छे उपाय के लिए चश्मा।
- एक उपयोगकर्ता के रूप में: सॉफ्टवेयर का उपयोग कैसे करें के बारे में सहायता मेनू, या एक सुलभ वेबसाइट के माध्यम से उपलब्ध दस्तावेज।
- व्यवसाय विश्लेषक के रूप में: दस्तावेज़ों के रूप में या एक सुलभ वेबसाइट के रूप में उपलब्ध दस्तावेज उपयोगी होते हैं। प्रोटोकॉल, उच्च-स्तरीय वास्तुकला और उपयोग के मामलों के बारे में विस्तार की एक मामूली राशि सबसे अच्छी है।
रखरखाव
इस दस्तावेज़ीकरण के स्रोत को कहां रखा जाए, यह आपके दर्शकों पर निर्भर करेगा, और आपके दर्शकों के लिए कौन लिख रहा है।
- केवल डेवलपर्स का एक घर है? कोड में सब कुछ रखें। यह इसे अद्यतन करने के लिए प्रोत्साहित करेगा। आपको एक ऐसी संस्कृति पर काम करने की आवश्यकता होगी जो कोड परिवर्तन के रूप में महत्वपूर्ण होने के लिए प्रलेखन अपडेट को प्रोत्साहित करती है।
- डेवलपर्स और प्रलेखन लेखकों का एक घर है? जिम्मेदारियों को विभाजित करें। डेवलपर्स के लिए डेवलपर ओरिएंटेड टूलिंग का उपयोग करें, डॉक्यूमेंटेशन लेखकों के लिए टूलिंग टूल का उपयोग करें।
जहां संभव हो, उस कोड के उदाहरणों को सुनिश्चित करें, या उपयोग के मामलों को निष्पादित किया जा सकता है। उनके निष्पादन और आंतरिक रूप से ध्वज विफलता को स्वचालित करें। संभावना है कि ये पृष्ठ खराब या खराब प्रलेखन हैं।
इसके अतिरिक्त जो भी उपकरण आप अपने दस्तावेज़ को लिखने के लिए चुनते हैं, आपको कोड के एक विशिष्ट संस्करण के साथ प्रलेखन के एक विशिष्ट संस्करण को जोड़ने के लिए एक विश्वसनीय साधन की आवश्यकता होती है। यह अभी भी एक भी सदाबहार तैनाती के साथ खुश बादल भूमि में फायदेमंद है।
समेकित प्रलेखन
एकीकरण के लिए कुछ प्रलेखन का उत्पादन करने की आवश्यकता हो सकती है, लेकिन ध्यान दें कि केवल उपयोगकर्ता को उन सभी दस्तावेज़ों तक पहुंचने के लिए एक ही स्थान की उम्मीद है जो उन्हें चाहिए।
API विश्लेषक, डिज़ाइन स्पेक्स और उपयोग परिदृश्यों के साथ अलग-अलग दस्तावेज़, या किसी वेबसाइट के अलग-अलग अनुभागों में स्थित होने से व्यावसायिक विश्लेषक काफी खुश हैं।
डेवलपर स्रोत से दिखाई देने वाली सभी चीज़ों को पसंद करता है, लेकिन उच्च-स्तरीय डिज़ाइन दस्तावेज़ों के एक जोड़े के लिए काफी खुश है, और विस्तृत प्रोटोकॉल विनिर्देश दस्तावेज़ों को बाहरी कोड के लिए, हालांकि अधिमानतः एक ही चेकआउट के भीतर।
आपका मुकदमा
ईमानदार होने के लिए, आपके विकी में प्रलेखन संभवतः आपके कोड-बेस में उसी तरह का प्रलेखन नहीं है। यह भी विलय करने के लिए समझ में नहीं आ सकता है।
दूसरी ओर दोनों को एकीकृत करके कुछ सरल तरीकों से वहन किया जा सकता है।
- सोर्स डॉक्यूमेंटेशन टूल (जैसे डॉक्सीजेन) html का उत्पादन कर सकते हैं, और एक विकी वेब-सर्वर पर रहता है। यह केवल विकी के साथ-साथ निर्मित संस्करण की सेवा करने और दोनों को जोड़ने के लिए एक सरल एकीकरण बिंदु होगा।
- कुछ विकी उत्पाद आपको एक फ़ाइल से सीधे विकी को चलाने की अनुमति देंगे जिसे आप कोड-बेस पर चेक-इन कर सकते हैं। यह डॉक्यूमेंट को कोड में जोड़े रखते हुए एक सरल wysiwyg टूलिंग देता है।
- पीडीएफ जैसे अन्य प्रारूपों को भी समायोजित किया जा सकता है, लेकिन यह आपके द्वारा उपयोग किए जाने वाले विशिष्ट टूलिंग के लिए नीचे आ जाएगा। यह आपकी विकी को मार्कडाउन फ़ाइलों में परिमार्जन करने और डॉक्सीजीन (या अन्य उपकरण) के माध्यम से खिलाने के लिए समझ में आ सकता है। यह विकी और पीडीएफ को अलग से पीडीएफ बनाने और पीडीएफ विलय उपकरण का उपयोग करने के लिए समझ में आता है।
दिन के अंत में, यह पता लगाएं कि किस प्रलेखन प्रणाली में रखरखाव की लागत कम है, और डेवलपर्स, व्यावसायिक विश्लेषकों और उपयोगकर्ताओं के अपने दर्शकों द्वारा देखे गए उच्च गुणवत्ता वाले उत्पाद को वितरित करने में आपकी सहायता करता है। कुछ भी जो इन समूहों में से किसी को भी बाधित करता है, वह उत्पादों की गुणवत्ता को कम करेगा।