इंजीनियर-लिखित दस्तावेज़ों में सामान्य गलतियाँ और उन्हें कैसे ठीक करें

पिछले छह महीनों में, हमारी विकास टीम ने "डॉक्स-एज़-कोड" दृष्टिकोण अपनाया है (आप इसमें हमारी यात्रा के बारे में अधिक जान सकते हैं लेख ). तकनीकी प्रभाग के मेरे सहयोगियों द्वारा बनाए गए दस्तावेज़ों की नियमित रूप से समीक्षा करते हुए, मैंने तकनीकी दस्तावेज़ीकरण लिखने में पाए जाने वाले सबसे आम मुद्दों की एक सूची तैयार की।

लेख में, मैं आपको दिखाऊंगा कि "डॉक्स-एज़-कोड" दृष्टिकोण के टूल का उपयोग करके इन समस्याओं को कैसे ठीक किया जाए।

अंक 1. "दस्तावेज़ लिखना हमारी ज़िम्मेदारी के अंतर्गत नहीं है"

तदर्थ आधार पर दस्तावेज़ीकरण से निपटना पूरी विकास टीम के लिए अपने पैर पर कुल्हाड़ी मारने जैसा है। यदि टीम में क्षमता की कमी है, तो दस्तावेज़ीकरण रखरखाव को अधिक प्रौद्योगिकी-संचालित और पूर्वानुमानित बनाना एक अनिवार्य कारण है।

हल करना:

• दस्तावेज़ीकरण के विकास के लिए "डॉक्स-एज़-कोड" दृष्टिकोण को एकीकृत करें। इस तरह, आप तकनीकी ऋण जमा होने के जोखिम के बिना, कोडबेस के साथ-साथ दस्तावेज़ को लगातार अपडेट कर सकते हैं।
• एक ऐसा स्थान या मंच विकसित या एकीकृत करें जो तकनीकी दस्तावेज़ प्रस्तुत कर सके और सूचना के एकल स्रोत के रूप में काम कर सके।
• एक एकीकृत विकास वातावरण (आईडीई) का उपयोग करें। एक आईडीई आपको प्लगइन्स को शामिल करने और दस्तावेज़ीकरण विकास के लिए कस्टम स्क्रिप्ट बनाने में सक्षम बनाता है। विचार डॉक्स लेखन के लिए एक उत्कृष्ट उपकरण है, लेकिन आपके पसंदीदा एप्लिकेशन भी हो सकते हैं।
• टाइपिंग त्रुटियों से बचने के लिए वर्तनी-जांच प्लगइन स्थापित करें। अपने IDE में प्लगइन जोड़ना एक त्वरित और आसान प्रक्रिया है।
• कंपनी के भीतर दस्तावेज़ विकसित करने के लिए एक मानकीकृत दृष्टिकोण स्थापित करने के लिए, तकनीकी लेखन समुदाय (यदि आपके पास कोई है) से अंतर्दृष्टि को ध्यान में रखते हुए, आपकी कंपनी द्वारा विशेष रूप से तैयार किए गए आंतरिक दिशानिर्देशों को अपनाएं। इन दिशानिर्देशों का पालन करने से दस्तावेज़ीकरण प्रक्रिया सुव्यवस्थित हो जाएगी, जिससे सटीक रूप से क्या और कैसे लिखना है, इस पर विचार करने में समय की बचत होगी।
• दस्तावेज़ों की समीक्षा के समय को उल्लेखनीय रूप से कम करने या समाप्त करने के लिए दिशानिर्देशों के आधार पर जांच को स्वचालित करें।
• हर संभव टेम्पलेट बनाएं और दस्तावेज़ीकरण घटकों को मानकीकृत करने पर टीम से सहमत हों।

मैं मूल्यवान संसाधन प्रदान करूंगा जो तकनीकी दस्तावेज़ीकरण के साथ काम करते समय आपका आत्मविश्वास बढ़ाएगा। मेरा मानना है कि ये संसाधन आपको तकनीकी दस्तावेज़ों को प्रभावी ढंग से संभालने में सक्षम बनाने के लिए पर्याप्त व्यापक हैं:

• " Google डेवलपर दस्तावेज़ीकरण शैली मार्गदर्शिका "डेवलपर दस्तावेज़ीकरण के लिए एक व्यापक पुस्तिका के रूप में कार्य करता है। इसमें फ़ॉर्मेटिंग, विराम चिह्न, सूचीकरण और कोड ब्लॉक जोड़ने के बारे में आपको जो कुछ जानने की ज़रूरत है उसे शामिल किया गया है। यह मार्गदर्शिका पर्याप्त है और हमारे आंतरिक दिशानिर्देशों को विकसित करने के लिए एक मूल्यवान संदर्भ रही है, जिसमें से हमने कुछ उधार लिया है सर्वोत्तम प्रथाएं।
• “ डेवलपर्स के लिए दस्तावेज़ "डेवलपर दस्तावेज़ीकरण के साथ काम करने वाले किसी भी व्यक्ति के लिए यह अवश्य पढ़ी जाने वाली पुस्तक है, चाहे वे इसे विकसित कर रहे हों, लिख रहे हों या रखरखाव कर रहे हों। इस पुस्तक में तकनीकी लेखन के क्षेत्र में कई प्रसिद्ध और सम्मानित लेखकों को शामिल किया गया है।

• " डॉक्स लाइक कोड "ऐनी जेंटल, एक तकनीकी लेखिका, एक व्यावहारिक मार्गदर्शिका है जो ओपनस्टैक में दस्तावेज़ीकरण संस्कृति को प्रदर्शित करती है। व्यावहारिक उदाहरणों के माध्यम से, लेखक बताते हैं कि GitHub में दस्तावेज़ीकरण का प्रबंधन क्यों किया जाना चाहिए और प्रभावी दस्तावेज़ीकरण के लिए तकनीकी प्रक्रियाओं को कैसे कार्यान्वित किया जाना चाहिए। पुस्तक मूल्यवान भी प्रदान करती है चाहे आप डेवलपर हों या तकनीकी लेखक, पेशेवर दस्तावेज़ लिखने पर अंतर्दृष्टि।

• मैं तकनीकी दस्तावेज लिखने के लिए आंतरिक दिशानिर्देशों का भी उल्लेख करूंगा, जिसमें टेम्पलेट और प्रारूपण नियम शामिल होने चाहिए। ऐसे दिशानिर्देश हर कंपनी में मौजूद हैं। आमतौर पर, उन्हें तकनीकी लेखक-अग्रणी और डेव डॉक्स चैंपियन के साथ सहयोगात्मक रूप से विकसित किया जाता है और टीम के भीतर दस्तावेज़ीकरण संस्कृति बढ़ने के साथ विकसित होता है।

अंक 2. दस्तावेज़ीकरण एकल लिखना

संपूर्ण दस्तावेज़ को अकेले विकसित करने और फिर उसे समीक्षा के लिए प्रस्तुत करने से अनावश्यक या अप्रासंगिक दस्तावेज़ बनाने का जोखिम होता है जो इच्छित उद्देश्य के साथ संरेखित नहीं हो सकता है।

हल करना:

• हमेशा एक रूपरेखा के साथ शुरुआत करें और इसे अपनी टीम के नेतृत्वकर्ता, उत्पाद स्वामी, तकनीकी लेखक, या अपनी विशेषज्ञ राय देने के इच्छुक किसी सहकर्मी के साथ साझा करें।
• चरण दर चरण लिखें और उपरोक्त उल्लिखित सहकर्मियों पर समीक्षा के लिए पुल अनुरोध निर्दिष्ट करें।
• फीडबैक एकत्र करें और उस पर काम करें।
• टिप्पणियों पर विचार करें. और समीक्षा के स्वर को सहजता से लें, कभी-कभी यह कठोर हो सकता है, लेकिन यह समीक्षा प्रक्रिया की एक ख़ासियत मात्र है।
• दस्तावेज़ीकरण प्रवाह को नज़रअंदाज़ न करें. हमारी कंपनी में अपनाया गया सामान्य प्रवाह नीचे दिया गया है, लेकिन इस प्रवाह की विशेषताएं विकास टीम के साथ-साथ कंपनी पर भी निर्भर हो सकती हैं:

अंक 3. "जिन्हें समझना है वो समझ जायेंगे"

समय-समय पर मैं टीमों से सुनता हूं: "मैं विकास टीम के लिए लिख रहा हूं," "जिन्हें समझने की जरूरत है," "इस तरह यह हमारी टीम के भीतर ऐतिहासिक रूप से विकसित हुआ"।

लेकिन पेशेवर शब्दजाल और अंग्रेजीवाद के लिए उपयुक्तता और निरंतरता की आवश्यकता होती है। इनके अत्यधिक उपयोग से किसी पागल इंजीनियर के नोट्स जैसे दस्तावेज तैयार हो सकते हैं।

दस्तावेज़ीकरण के लिए, यथासंभव सरलतम शब्दों और संरचनाओं का उपयोग करें। मुख्य सिद्धांतों में से एक स्क्रॉलिंग के लिए लिखना है। दस्तावेज़ीकरण लिखना चुनौतीपूर्ण हो सकता है क्योंकि यह अक्सर व्यापक होता है, लेकिन पाठक शायद ही कभी इसे शुरू से अंत तक पढ़ते हैं। इसके बजाय, वे स्क्रॉल करते हैं या कीवर्ड खोज का उपयोग करते हैं। इसलिए, किसी भी भाग से खोलने पर पाठ आसानी से समझ में आना चाहिए।

हल करना:

• शब्दकोशों और वर्तमान मानदंडों (या बस उन्हें Google) का उपयोग करके अंग्रेजी शब्दों और पेशेवर शब्दजाल की जांच करें। यदि कोई शब्द शब्दकोश में मौजूद है, तो अपनी भाषा की शब्दावली के नियमों के अनुसार लिखें।
• यदि शब्द भाषा में मौजूद नहीं है, तो उसे मूल भाषा में लिखें, और कोष्ठक में अपनी भाषा में अनुवाद प्रदान करें।
• शब्द को शब्दावली अनुभाग में जोड़ें, और संक्षिप्ताक्षरों को संक्षिप्ताक्षरों और संक्षिप्ताक्षरों की सूची में जोड़ें। यह "मालिकाना" संक्षिप्ताक्षरों के लिए विशेष रूप से महत्वपूर्ण है (कोई फर्क नहीं पड़ता कि पीओ के बारे में कितना उल्लेख किया गया है या लिखा गया है, दस्तावेज़ीकरण पढ़ते समय इसका अर्थ अभी भी सामान्य प्रश्नों में से एक है)।
• संगति - पूरे दस्तावेज़ीकरण में चुनी गई लेखन शैली और संक्षिप्ताक्षरों पर टिके रहें (आपकी कंपनी में सभी उपलब्ध दस्तावेज़ों के लिए बेहतर)।
• दस्तावेज़ नेविगेशन की सावधानीपूर्वक योजना बनाएं. पूरे दस्तावेज़ को पढ़े बिना संबंधित अनुभाग को खोजने का एक त्वरित तरीका होना चाहिए। इसलिए, स्पष्ट और संक्षिप्त शीर्षकों के साथ सामग्री को सोच-समझकर तैयार करना आवश्यक है। सरलता और सुविधा के लिए आंतरिक दस्तावेज़ीकरण टेम्पलेट विकसित किए जाने चाहिए।

अंक 4. कई स्थानों पर एक साथ दस्तावेज़ लिखना

दस्तावेज़ीकरण के लिए, सत्य का एक एकल स्रोत होना महत्वपूर्ण है - एक ऐसा स्थान जहां आप इसकी सटीकता के बारे में चिंता किए बिना आवश्यक जानकारी पा सकते हैं। हमारे तकनीकी दस्तावेज़ीकरण के लिए, एक इन-हाउस विकसित प्लेटफ़ॉर्म ऐसी जगह के रूप में कार्य करता है। पुरानी जानकारी से किसी को गुमराह करने से रोकने के लिए विभिन्न स्थानों में दस्तावेज़ीकरण के विखंडन से बचना आवश्यक है।

हल करना:

• कहीं भी तकनीकी दस्तावेज़ प्रकाशित करने से पहले, सुनिश्चित करें कि यह कहीं और मौजूद नहीं है, अगर ऐसा सामने आता है कि कंपनी ज्ञान साझा करने के लिए कई स्थानों का उपयोग करती है।
• पुराने तकनीकी दस्तावेज़ों को संग्रहित करें या हटाएं (यदि आपके पास स्वामित्व है)। यदि आप समय से पहले हटाए जाने के बारे में चिंतित हैं (उदाहरण के लिए, पृष्ठ के बाहरी लिंक के कारण), तो एक कॉलआउट जोड़ें जिसमें कहा गया हो कि पृष्ठ पुराना हो गया है, और वैध दस्तावेज़ों का वर्तमान दस्तावेज़ीकरण स्थान, जहां आगे अपडेट किए जाने चाहिए।
• यदि आपको बहुमूल्य जानकारी या अंतर्दृष्टि मिलती है, तो उन्हें दस्तावेज़ीकरण में जोड़ें। इसे स्लैक या कहीं और न छोड़ें, विशेषकर निजी चैट में। साझा करने लायक ज्ञान!

अन्ना गोंचारोवा द्वारा पोस्ट किया गया