लक्षित दर्शकों की जरूरतों के अनुसार प्रलेखन व्यवस्थित करें।
आपके मामले में, प्राथमिक दर्शक जाहिरा तौर पर सॉफ़्टवेयर डेवलपर हैं। यहाँ पर विचार करने वाले भाग इस एक के विभिन्न "उप-श्रोताओं" को संबोधित करने के लिए हैं:
- नमस्ते दुनिया।
जो लोग इसका स्वाद जल्दी से प्राप्त करने के लिए तैयार हैं, बस नमूना आवेदन बनाएं और देखें कि यह कैसा दिखता है।
MySQL के "15 मिनट के नियम" से संबोधित किए गए दर्शकों की तरह सोचें :
... एक उपयोगकर्ता को MySQL को डाउनलोड करने और उसे डाउनलोड करने के 15 मिनट बाद चलाने में सक्षम होना चाहिए।
- बुनियादी बातों।
काम करने वाले सॉफ्टवेयर का उत्पादन शुरू करने के लिए आवश्यक चीजों को जल्दी से जानने के इच्छुक लोगों के लिए।
- उन्नत विषय।
डेवलपर्स के लिए पहले से ही अच्छी तरह से परिचित और मूल सिद्धांतों के साथ अभ्यास किया गया है, यह जानने के लिए दिलचस्पी है कि क्या है। मुख्यधारा के विषय जो बुनियादी बातों में शामिल नहीं किए गए हैं ।
- स्टाइल गाइड / अनुशंसित अभ्यास।
जिस तरह से आप चीजों को करने की सलाह देते हैं, उसके लिए विशेष सलाह और मार्गदर्शन।
यह सवाल इंगित नहीं करता है कि क्या यह आपके मामले में पर्याप्त दर्शक हो सकता है, इसलिए विचार करने के लिए विकल्प इसे उन्नत विषयों के एक भाग / परिशिष्ट के रूप में शामिल करने के लिए हैं या यहां तक कि इसे पूरी तरह से छोड़ देते हैं।
- क्वर्क्स।
अस्पष्ट विषयों, मुख्यधारा के बाहर, जो आपके दर्शकों के सुंदर सीमित अंश के लिए रुचि हो सकती है। उदाहरण के लिए, यदि आपके पास विरासत लाइन है, या विरासत के साथ अपग्रेड / माइग्रेशन / इंटरऑपरेबिलिटी जैसे सामान - इसे यहां रखें। यदि विशेष रूप से "विदेशी" वातावरण में कुछ फ़ंक्शन के लिए कुछ दुष्प्रभाव हैं, तो यह इस भाग में जाता है।
आपके द्वितीयक ऑडियंस मैनुअल के अनुरक्षक हैं। ये लोग आपके प्राथमिक दर्शकों के लिए कैसे काम करते हैं या बना सकते हैं, इसलिए आप उनकी जरूरतों और मुद्दों का बेहतर तरीके से ध्यान रखते हैं।
क्या होगा अगर मैनुअल में कुछ संदिग्ध / अस्पष्ट है? क्या होगा अगर यह पता चलता है कि विशेष अवधारणाओं की गहन व्याख्या से उस मैनुअल को पढ़ना बहुत मुश्किल हो जाएगा? क्या होगा अगर यह पता चला है कि मैनुअल के विशेष संस्करण में गलतियां हैं?
अनुरक्षकों के लिए विचार करने के लिए दो चीजें हैं:
- तकनीकी / औपचारिक विनिर्देश।
जब भी मैनुअल में कोई संदिग्ध / अस्पष्ट / कठिन विषय की व्याख्या करने के लिए होता है, तो उस पर सख्त और स्पष्ट, "आधिकारिक" बयान के लिए पाठक को विनिर्देश में विशेष पैराग्राफ के लिए भेजा जा सकता है। भाषा वाक्य रचना का सख्त और पूर्ण (और सबसे अधिक संभावना उबाऊ) विवरण वहां बेहतर होगा। विशिष्टता के
लिए सर्वोपरि विचार तकनीकी सटीकता और पूर्णता हैं, भले ही ये पठनीयता की कीमत पर हों।
- ऑनलाइन पूरक।
बस कुछ URL आरक्षित करें और इसे आपके द्वारा जारी किए गए प्रत्येक दस्तावेज़ की शुरुआत में डालें, ताकि लोग सोचें कि उन्होंने अभी जो नरक पढ़ा है, वह वहां जा सकता है (मैनुअल अनुरक्षकों के बजाय) और गलती से बताई गई गलती को ढूंढ सकते हैं।
इरेटा> फंडामेंटल> रिलीज 2.2> टाइपो पृष्ठ 28 पर, दूसरा वाक्य भाग्य के साथ शुरू होता है , इसके बजाय लॉक पढ़ें ।
लॉकिंग रणनीतियों, प्रदर्शन संबंधी विवरण जैसी अवधारणाओं को शामिल किया जाना चाहिए (संभवत: आंशिक रूप से) जहां आपको उम्मीद है कि लक्षित दर्शकों को इसकी आवश्यकता है।
उदाहरण के लिए मैनुअल मेंटेनर्स जाहिर तौर पर कंसीडर के पूर्ण, सटीक विवरण और फॉर्मल स्पेसिफिकेशन में लॉक करने के इच्छुक होंगे - इसे वहां रखें। मूल सिद्धांतों या उन्नत विषयों के पाठकों को विनिर्देशन से निकाले गए अवलोकन / परिचय / मार्गदर्शिका में रुचि हो सकती है और उनकी आवश्यकताओं आदि के अनुरूप हो सकता है।
यह आपके जैसी अन्य भाषाओं के लिए प्रदान किए गए संदर्भ प्रलेखन के तुलनात्मक अध्ययन की व्यवस्था करने में सहायक हो सकता है। इस अध्ययन का लाभ उन लोगों द्वारा प्राप्त किए गए अनुभव पर रखा गया है, जिन्होंने इसे पहले किया था और यह सीखा कि वे गलतियों से कैसे बचें।
अंतिम लेकिन कम से कम नहीं, सॉफ्टवेयर विकास के समान एक तरह से प्रलेखन विकास स्थापित करने पर विचार करें। मेरा मतलब है कि संस्करण नियंत्रण, नियमित रिलीज, अंक ट्रैकिंग, गुणवत्ता आश्वासन आदि जैसी चीजें आप कुछ समझौता करना चाहते हैं, हालांकि अगर यह पता चले कि आपका तकनीकी लेखक वास्तव में इस तरह से सामान के साथ सहज नहीं है। हम संपूर्ण विकास प्रक्रिया के लिए "बदले में" भ्रामक सामग्री प्राप्त नहीं करना चाहते हैं, क्या हम?