तांत्रिक दस्तऐवजीकरण (Technical documentation) ही कोड कंपाईल झाल्यानंतर पूर्ण केली जाणारी एखादी दुय्यम गोष्ट नाही. ते प्रत्येक सॉफ्टवेअर प्रकल्पाच्या केंद्रस्थानी असते, ज्यामुळे एखादा नवीन डेव्हलपर त्याच्या पहिल्याच दिवशी बग (bug) फिक्स करू शकेल की नाही, किंवा एखादा वापरकर्ता गोंधळून पाच मिनिटांतच तुमचा उत्पादन सोडून जाईल, हे ठरते. चांगले दस्तऐवज वापरकर्त्यांना प्रत्यक्ष कामे पूर्ण करण्यास मदत करतात. ते भविष्यातील मेंटेनर्सना एखादा मॉड्यूल का अस्तित्वात आहे आणि सर्व काही बिघडवून न टाकता त्यात बदल कसा करायचा हे समजून घेण्यास मदत करतात. तरीही, अनेक टीम्स दस्तऐवजीकरणाकडे एक विचार न केलेला भाग, घाईघाईने तयार केलेली README, किंवा कुजत राहिलेले विकी (wiki) पेज म्हणून पाहतात. खरोखर उपयुक्त दस्तऐवजीकरण लिहिणे हे एक कौशल्य आहे जे तुम्ही जाणीवपूर्वक सुधारू शकता.
लिहिण्यापूर्वी तुमच्या वाचकांना ओळखा
एकही हेडिंग टाईप करण्यापूर्वी, तुमचे वाचक कोण आहेत हे ठरवा. कनेक्शन पूल सेटिंग्स शोधणारा डेटाबेस ॲडमिनिस्ट्रेटर (database administrator) आणि React component props शोधणारा फ्रंट-एंड डेव्हलपर यांच्यात काहीही साम्य नसते. एंड-युजर्सना (End-users) आर्किटेक्चर डायग्रामची नाही, तर नंबरिंग केलेले स्टेप्स आणि स्क्रीनशॉट्सची गरज असते. त्यांना रेंडरिंग पाईपलाईन कशी काम करते हे जाणून घेण्यात रस नसतो, तर PDF एक्सपोर्ट कसे करायचे हे जाणून घ्यायचे असते. तुमच्या लायब्ररीचे इंटिग्रेशन करणाऱ्या डेव्हलपर्सना अचूक फंक्शन सिग्नेचर (function signatures), एरर कोड्स आणि कॉपी-पेस्ट करता येण्यासारखे कोड स्निपेट्स (snippets) लागतात. सिस्टम ॲडमिनिस्ट्रेटर्सना इन्स्टॉलेशनसाठी आवश्यक गोष्टी (prerequisites), एन्व्हायरनमेंट व्हेरिएबल्स आणि सर्वात सामान्य त्रुटींपासून (failure modes) सुरू होणारे ट्रबलशूटिंग फ्लो आवश्यक असतात.
जर तुम्ही एकाच मोठ्या मजकुराद्वारे या तिन्ही गटांना सेवा देण्याचा प्रयत्न केला, तर कोणाचेही समाधान होणार नाही. स्वतंत्र मार्ग तयार करा. अगदी एकाच पेजवर सुद्धा "ऑपरेटर्ससाठी" आणि "क्लायंट डेव्हलपर्ससाठी" यांसारख्या स्पष्ट हेडिंग्सचा वापर करून विभागणी करता येते. "हा परिच्छेद माझ्यासाठी आहे का?" असा विचार करण्याची मानसिक अडचण दूर करणे हे तुमचे ध्येय असावे.
अनावश्यक गोष्टी टाळा
स्पष्टता ही चपळतेपेक्षा (cleverness) महत्त्वाची आहे. लहान वाक्यांचा वापर करा. 'Active voice' वापरा. "The database should be initialized by the user" पेक्षा "Initialize the database" हे अधिक स्पष्ट आहे. जेव्हा तुम्हाला "idempotency" किंवा "serialization" सारख्या तांत्रिक शब्दांचा वापर करावा लागतो, तेव्हा त्याचा अर्थ लगेच स्पष्ट करा किंवा ग्लॉसरीची (glossary) लिंक द्या. वाचकाला आधीपासूनच सर्व माहिती आहे असे गृहीत धरू नका.
एक व्यावहारिक चाचणी: तुमचा परिच्छेद मोठ्याने वाचून पहा. जर तुमचा श्वास कोंडला, तर समजून जा की वाक्य खूप मोठे आहे. दुसरी चाचणी: अलंकारिक क्रियापदांऐवजी साधी क्रियापदे वापरा. जर "utilize the API" ऐवजी अर्थ न बदलता "use the API" म्हणता येत असेल, तर तो बदल करा. साधी भाषा म्हणजे 'डंबड-डाउन' (dumbed-down) भाषा नव्हे. याचा अर्थ कॉर्पोरेट शब्दांचा अनावश्यक वापर न करता अचूक भाषा वापरणे असा आहे.
खरोखर उपयुक्त ठरेल अशी रचना
विस्कळीत मॅन्युअलमुळे दस्तऐवज नसण्यापेक्षा जास्त वेळ वाया जातो. तुमच्या दस्तऐवजीकरणाचा विचार एका 'फनेल' (funnel) प्रमाणे करा. सर्वात वर, एक संक्षिप्त आढावा (overview) द्या जो प्रकल्प काय करतो आणि तो कोणासाठी महत्त्वाचा आहे हे स्पष्ट करेल. त्यानंतर इन्स्टॉलेशन सूचना द्या, ज्यामध्ये वाचकाच्या स्थानिक सेटअपबद्दल (local setup) काहीही गृहीत धरलेले नसेल. त्यानंतर ट्युटोरियल्स जोडा जे सुरुवातीपासून शेवटपर्यंत पूर्ण आणि वास्तववादी परिस्थिती (scenarios) समजावून सांगतील. त्यानंतर API संदर्भ (references) येतात. हे सर्वसमावेशक पण सहज वाचता येण्यासारखे (scannable) असावेत; ते वर्णक्रमानुसार (alphabetical order) न ठेवता रिसोर्स किंवा फंक्शननुसार गटबद्ध केलेले असावेत. शेवटी, विशिष्ट समस्यांवर उपाय देणारे ट्रबलशूटिंग गाइड्स ठेवा. "Connection refused" मेसेज येणाऱ्या वापरकर्त्याला "Permission denied" येणाऱ्या वापरकर्त्यापेक्षा वेगळा उपाय हवा असेल. त्रुटींचे वर्गीकरण अमूर्त श्रेणींनुसार (abstract category) न करता, मेसेज किंवा संदर्भांनुसार करा.
लिस्ट आणि कोड ब्लॉक्स (code blocks) सलग मजकूर तोडतात आणि वाचकांना त्यांना हव्या असलेल्या नेमक्या कमांड शोधण्यास मदत करतात. योग्य ठिकाणी वापरलेली बुलेट लिस्ट गोंधळात टाकणाऱ्या परिच्छेदाचे रूपांतर कृतींच्या क्रमात करू शकते.
फक्त सांगू नका, दाखवा
अमूर्त स्पष्टीकरणे वापरकर्त्यांना निराश करतात. जर तुम्ही एखादे टूल कॉन्फिगर कसे करायचे याचे वर्णन करत असाल, तर फाईलमध्ये नेमका काय मजकूर असावा ते दाखवा. इन्स्टॉलेशनसाठी, इनिशियलायझेशनसाठी आणि सामान्य कॉन्फिगरेशनसाठी कोड स्निपेट्स द्या. इनपुटचे नमुने आणि अपेक्षित आउटपुट शेजारी-शेजारी दाखवा. जर तुमचा API JSON रिटर्न करत असेल, तर JSON दाखवा. जर CLI टूल टेबल फॉरमॅटमध्ये आउटपुट देत असेल, तर टेबल दाखवा. वर्कफ्लोचे वर्णन करणे हे प्रत्यक्ष प्रात्यक्षिकासारखेच आहे, असा विश्वास कधीही ठेवू नका.
सर्वात महत्त्वाचे म्हणजे, प्रकाशित करण्यापूर्वी प्रत्येक उदाहरण स्वच्छ वातावरणात (clean environment) तपासा. तुमचा स्वतःचा कोड स्निपेट एका नवीन कंटेनर किंवा व्हर्च्युअल मशीनमध्ये चालवून पहा. जर एखादी डिपेंडन्सी (dependency) सांगायला विसरल्यामुळे तो कोड चालला नाही, तर तुम्ही स्वतःला भविष्यातील अनेक समस्यांपासून वाचवले आहे. तांत्रिक लेखनात (technical writing) प्रत्यक्ष उदाहरणे हा गुंतवणुकीवर मिळणारा सर्वात मोठा परतावा आहे, कारण ती अनिश्चिततेचे रूपांतर कृतीत करतात.
ते जिवंत ठेवा
दस्तऐवजीकरण हे कोडपेक्षा वेगाने जुने होते. एखादे मेथड सिग्नेचर बदलते, डिफॉल्ट पोर्ट बदलतो, एखादी डिपेंडन्सी बदलली जाते आणि अचानक तुमच्या सूचना निरर्थक ठरतात...