अच्छा डिज़ाइन डॉक्यूमेंट कैसे लिखें

• डिज़ाइन डॉक्यूमेंट सिस्टम की implementation strategy, constraints, और trade-offs को व्यवस्थित करने वाली एक तकनीकी रिपोर्ट है
• डिज़ाइन डॉक्यूमेंट का काम पाठक को यह भरोसा दिलाना है कि यह डिज़ाइन दिए गए संदर्भ के लिए उपयुक्त है
• दस्तावेज़ की संरचना महत्वपूर्ण है, और तार्किक प्रवाह के माध्यम से यह सुनिश्चित होना चाहिए कि पाठक सामग्री से चौंके नहीं
• संपादन के जरिए अनावश्यक शब्दों को कम करना और पाठक के ध्यान जैसे सीमित संसाधन को बचाना ज़रूरी है
• छोटे पैराग्राफ और appendix का उपयोग, तथा अभ्यास के माध्यम से दस्तावेज़ लेखन क्षमता में सुधार महत्वपूर्ण है

---

परिभाषा

• डिज़ाइन डॉक्यूमेंट, trade-offs और constraints के संदर्भ में सिस्टम implementation strategy को व्यवस्थित करने वाली एक तकनीकी रिपोर्ट है

लक्ष्य

• जैसे गणित में proof किसी theorem को स्वीकार्य बनाता है, वैसे ही डिज़ाइन डॉक्यूमेंट का उद्देश्य पाठक को यह विश्वास दिलाना है कि संबंधित डिज़ाइन सर्वोत्तम है
• डिज़ाइन प्रक्रिया में लिखने का कार्य स्वयं सोच की कठोरता बढ़ाता है
• डिज़ाइन डॉक्यूमेंट लिखते समय धुंधले विचारों को ठोस सोच में बदला जा सकता है

संगठन

• अच्छे डिज़ाइन डॉक्यूमेंट की संरचना उतनी ही महत्वपूर्ण है जितनी code organization
• जैसे शुरुआती लोग कोड लिखते हैं, वैसे ही बहुत से लोग 'spaghetti design document' लिखने की प्रवृत्ति रखते हैं
• यदि वाक्यों को तार्किक क्रम के बिना रखा जाए, तो पाठक के लिए संदर्भ का पीछा करना कठिन हो जाता है और भ्रम पैदा होता है
• एक उत्कृष्ट दस्तावेज़ में पाठक चौंकना नहीं चाहिए; प्रवाह स्वाभाविक होना चाहिए, और हर वाक्य पिछले बिंदु के आधार पर स्वाभाविक रूप से आगे बढ़ना चाहिए
• लक्ष्य यह है कि पाठक की वर्तमान सोच की स्थिति को समझकर उसे चरणबद्ध तरीके से नई स्थिति तक ले जाया जाए
• संभावित आपत्तियों को पहले से दूर करना चाहिए, और पाठक के प्रतिवाद करने से पहले ही स्पष्टीकरण देना चाहिए

संपादन

• सामग्री को अच्छी तरह व्यवस्थित करने के बाद अनावश्यक शब्द हटाने (editing) का चरण महत्वपूर्ण है
• पाठक का ध्यान एक सीमित संसाधन है, इसलिए अनावश्यक जानकारी को साहसपूर्वक हटाना चाहिए
• एक draft से लगभग 30% निरर्थक अभिव्यक्तियाँ कम की जा सकती हैं
• दूसरों के दस्तावेज़ संपादित करते हुए आलोचनात्मक दृष्टि विकसित की जाए, तो अपनी लिखाई को भी अधिक प्रभावी ढंग से निखारा जा सकता है
• छोटे tweets (280-character limit) के साथ अभ्यास करना भी सोच को सरल बनाने और संक्षेपण क्षमता बढ़ाने में मदद करता है

अनुभव और अभ्यास

• दोहराया गया अभ्यास जितना कौशल बढ़ाता है, उतना तेज़ कोई और रास्ता नहीं है
• Amazon में document-first culture का अनुभव, दस्तावेज़ लेखन क्षमता सुधारने में बहुत सहायक रहा
• महत्वपूर्ण मीटिंग्स में 1–6 पन्नों के डिज़ाइन डॉक्यूमेंट बाँटने के बाद, सभी लोग चुपचाप पढ़ते हैं और मार्जिन में अपने विचार लिखते हैं
• feedback लेते हुए लेखन कौशल को वास्तव में बेहतर बनाया जा सकता है

ठोस सुझाव

छोटे पैराग्राफ का उपयोग

• डिज़ाइन डॉक्यूमेंट को लगातार संक्षिप्त bullet points के माध्यम से प्रवाह बनाना चाहिए
• हर bullet point (observation, idea, problem, improvement आदि) एक अवधारणा पर केंद्रित छोटे पैराग्राफ से बना होना चाहिए
• हर पैराग्राफ इतना स्पष्ट होना चाहिए कि उसे एक वाक्य में सारांशित किया जा सके; इससे पाठक की short-term memory पर भार कम होता है

appendix का उपयोग

• जटिल calculations या simulation results को दस्तावेज़ के मुख्य भाग में नहीं, बल्कि appendix में विस्तार से रखना चाहिए, और मुख्य भाग में उनका केवल संक्षिप्त footnote जैसा उल्लेख होना चाहिए
• मुख्य निष्कर्ष समझने के लिए appendix आवश्यक नहीं होना चाहिए; इसे उन पाठकों के लिए दिया जाना चाहिए जो अधिक गहराई में देखना चाहते हैं

संपादन उदाहरण

• (संपादन से पहले, लंबा पैराग्राफ):

  हर bullet point दस्तावेज़ में एक अलग पैराग्राफ होना चाहिए। हर पैराग्राफ को एक वाक्य में सारांशित किया जा सकना चाहिए। वास्तव में उसका एक ही वाक्य होना ज़रूरी नहीं है; अवधारणा समझाने के लिए अतिरिक्त व्याख्या हो सकती है। लेकिन पढ़ने के बाद पाठक उसे एक वाक्य में समेट सके, यह ज़रूरी है।

• (संपादन के बाद, संक्षिप्त पैराग्राफ):

  हर bullet point एक पैराग्राफ होना चाहिए और उसे एक वाक्य में सारांशित किया जा सकना चाहिए। उसका वास्तव में एक ही वाक्य होना ज़रूरी नहीं है, और ज़रूरत पड़ने पर अतिरिक्त व्याख्या जोड़ी जा सकती है। लेकिन पढ़ने के बाद उसे एक वाक्य में संक्षेपित किया जा सकना चाहिए।

समापन

• डिज़ाइन डॉक्यूमेंट सोच की कठोरता, तार्किक प्रवाह, पाठक-केंद्रित संपादन, और दोहराए गए अभ्यास के माध्यम से क्षमता विकसित करने की एक महत्वपूर्ण प्रक्रिया है

[GN⁺]

Hacker News टिप्पणियाँ

• लेख से खास तौर पर प्रभावशाली लगी दो उद्धरणों का परिचय दिया गया है। पहला X के स्क्रीनशॉट से है: "लिखने की प्रक्रिया में आइडिया 10 गुना बेहतर हो जाते हैं"। दूसरा शुरुआत का यह वाक्य है: "जिस सबसे महत्वपूर्ण व्यक्ति को आपको मनाना है, वह स्वयं लेखक है।" कई सालों से इंडस्ट्री में काम करने के बाद भी अब तक ऐसे लोगों का होना हैरान करता है जो डिज़ाइन दस्तावेज़ों की ज़रूरत के खिलाफ हैं। Leslie Lamport ने कहा था कि "लेखन वह तरीका है जिससे प्रकृति हमें बताती है कि हमारी सोच कितनी बेतरतीब है।" अगर तकनीकी लेखन कौशल और बेहतर करना चाहते हैं, तो Write Like an Amazonian(https://medium.com/@apappascs/…) पढ़ने की सिफारिश है
  • शायद "विशेषणों को डेटा में बदलो" वाली सलाह तकनीकी इंडस्ट्री में बहुत फैल गई है, इसलिए आजकल जो भी रिज़्यूमे देखता हूँ वे संख्याओं से भरे होते हैं, यहाँ तक कि उनका अर्थ समझना मुश्किल हो जाता है
• डिज़ाइन reviewer के रूप में, एक बात है जिसे हर दस्तावेज़ लेखक को ज़रूर भीतर तक उतार लेना चाहिए। वह यह कि "अच्छा दस्तावेज़ पाठक को समस्या और सोच के मॉडल को इस तरह समझाता है कि कई हफ्तों की सोच-विचार से निकला समाधान जैसे ही सामने आता है, वह स्वाभाविक रूप से उसे स्वीकार कर ले।" मेरा पसंदीदा उद्धरण है: "अगर मेरे पास और समय होता, तो मैं एक छोटा पत्र लिखता।" मेरा मानना है कि डिज़ाइन दस्तावेज़ों को जटिल चीज़ों को सरल बनाना चाहिए; यह वह जगह नहीं है जहाँ डेवलपर ने जो भी मोड़, उलझनें और विफलताएँ झेली हों, सब कुछ ज्यों का त्यों डाल दिया जाए। ऐसी बातें शामिल करने लायक हो सकती हैं, लेकिन उन्हें अलग दस्तावेज़ या appendix में रखना बेहतर है। आगे का रास्ता सरल ढंग से दिखाना ज़रूरी है
  • मुझे "और समय, छोटा पत्र" वाली अभिव्यक्ति ज़्यादा पसंद है
  • मैं हमेशा खुद से ये सवाल पूछता हूँ: "क्या इस विषय पर बेकार की बहस शुरू होगी?", "क्या वह बहस करने लायक है?" मेरा लक्ष्य यह है कि नया पाठक बिना कठिनाई चर्चा में शामिल हो सके, और गैर-महत्वपूर्ण बातों पर विवाद पैदा न हो
• Amazon की मीटिंग्स presenter द्वारा गद्य-रूप के दस्तावेज़ बाँटने से शुरू होती हैं। सब चुपचाप बैठकर दस्तावेज़ पढ़ते हैं और हाशिए पर लाल पेन से नोट्स और सवाल लिखते हैं। मैंने खुद Amazon में काम नहीं किया है, लेकिन यह तरीका हैरान कर देने वाला प्रभावी लगता है, और जो लोग अपने अनुभव बताते हैं वे आम तौर पर इसे पसंद करते हैं। कीमती मीटिंग समय केवल साथ बैठकर पढ़ने में खर्च करना अक्षम लग सकता है, लेकिन अगर लोग पहले से पढ़कर आएँ तो मीटिंग और छोटी हो सकती है। रीयल-टाइम सामूहिक पढ़ाई में या तो धीमे पाठकों का इंतज़ार करना पड़ता है, या संदर्भ की कमी के कारण समझ का स्तर अलग-अलग होता है, और सब कुछ कुछ धुंधला-सा चलता रहता है। Google में डिज़ाइन review करते समय मैंने अक्सर देखा कि ज़्यादातर प्रतिभागी बिना तैयारी पहली बार दस्तावेज़ वहीं देखकर चर्चा में शामिल होते थे। मुझे लगता है कि ऐसा इसलिए था क्योंकि Google में मजबूत दस्तावेज़ संस्कृति नहीं थी, और team lead या manager का बिना तैयारी आना भी चुपचाप स्वीकार्य था। अगर केवल मीटिंग से पहले ठीक से पढ़कर आने की संस्कृति बैठ जाए, तो मीटिंग का समय कहीं अधिक कुशलता से इस्तेमाल हो सकता है
  • लोग कहते हैं कि मीटिंग से पहले पढ़कर आने से मीटिंग का समय घटता है, लेकिन Amazon की यह प्रथा इस वास्तविकता का जवाब है कि लोग वास्तव में पहले से पढ़कर नहीं आते। पहले के एक संबंधित लेख में देखा था कि पहले से पढ़ने और तैयारी की मजबूत संस्कृति बनाना लगभग असंभव था। हर प्रतिभागी ठीक पहले वाली मीटिंग के कारण तैयारी नहीं कर पाता था, और उसके पहले भी एक और मीटिंग होती थी। सैद्धांतिक रूप से यह आलोचना की जा सकती है कि मीटिंग्स कम क्यों नहीं कर दी जातीं, लेकिन व्यवहार में वे मीटिंग्स मूल्यवान थीं, और पढ़ने का समय शामिल होने पर भी पर्याप्त निर्णय हो जाते थे। अंततः नतीजों पर ध्यान देना चाहिए, और वास्तव में Amazon में लोगों को लगता है कि इस तरीके के फायदे नुकसान से बड़े हैं
  • दस्तावेज़ कब पढ़ा जाता है, यह इतना महत्वपूर्ण क्यों है, इस पर सवाल है। अगर अधिक समय चाहिए तो मीटिंग का समय बढ़ाया जा सकता है। नुकसान बस इतना है कि मीटिंग शेड्यूल करना कठिन हो सकता है, लेकिन कुल समय तो नहीं बदलता—ऐसी राय है
  • मेरा मानना है कि तब और ज़्यादा समय बर्बाद होता है जब सबकी समझ का स्तर समान न हो, या इस बात की चिंता हो कि किसी का corner case छूट न जाए
  • यह अनुभव भी बताया गया कि अगर किसी बात पर वास्तव में मीटिंग में चर्चा न हो, तो कुछ भी आगे नहीं बढ़ता
• स्पष्टता और editing पर बहुत अच्छी सलाह है। कमजोरी यह है कि दस्तावेज़ approve होने के बाद उनका रखरखाव कैसे किया जाए। रखरखाव न हो तो चीज़ें 'डिज़ाइन पुरातत्व' जैसी स्थिति में गिर जाती हैं। कुछ साल पहले Andrew Harmel-Law ने संगठन के भीतर architecture decisions को प्रभावी ढंग से रिकॉर्ड करने के लिए Architecture Decision Records(ADRs) का प्रस्ताव रखा था, और यह तरीका मददगार हो सकता है। ADRs कोड के बगल में होते हैं (जैसे: adr/001-use-postgres.md), और उनमें संदर्भ, निर्णय और status संक्षेप में दर्ज किया जाता है। इसलिए हर PR में उन्हें आसानी से review किया जा सकता है, और परिस्थिति बदलने पर आसानी से बदला भी जा सकता है। मूल निर्णय के पीछे का आधार भी महीनों बाद तक खोजा जा सकता है। [लिंक: https://martinfowler.com/articles/…]
  • अगर ऐसा तरीका अपनाया जाए, तो क्या Security, Privacy, Compliance जैसी पूरे संगठन की समितियाँ हर उस PR की reviewer बनेंगी जिसमें ADR जुड़ा हो? संदेह है कि ऐसे PR 90 दिनों के भीतर merge हो पाएँगे या नहीं
  • MF.com(https://thoughtworks.com/radar/techniques/…) लिंक पूरा पढ़ना चाहिए, लेकिन "Advice Process" आखिर में बस "सबसे बात करो" पर खत्म हो जाता है। जिन लोगों के पदनाम में "Managing" आता है, वे शायद इसी बिंदु पर रुचि खो देंगे। असली बात शायद "चार सहायक तत्वों" में है, लेकिन ADRs के बारे में और जानने के लिए इस लिंक पर गया तो आखिर में PDF(https://thoughtworks.com/content/dam/…) डाउनलोड करनी पड़ी। अच्छा होगा अगर ADRs आखिर हैं क्या, यह स्पष्ट परिभाषा के साथ बताया जाए
  • Session messenger एक अच्छा उदाहरण है। डिज़ाइन और architecture में इतने सारे बदलाव हुए हैं कि यह कैसे काम करता है, इस पर कोई आधिकारिक और प्रामाणिक जानकारी नहीं है। वैसे अगर सुरक्षित messaging चाहिए, तो बस Signal इस्तेमाल कर लो
• मेरे अनुभव में, संगठन और स्पष्टता ही वे सबसे बड़े अवरोध हैं जो SW engineers को दस्तावेज़ लेखन में बेहतर बनने से रोकते हैं। लेखक की 'code spaghetti' वाली उपमा विचारों के संगठन के महत्व को समझाने के लिए बहुत अच्छी लगी। मैंने भी कभी इसी तरह की बात अलग तरीके से कहने की कोशिश की थी, और आगे से शायद यही उपमा इस्तेमाल करूँगा। मैंने पहले एक मिलता-जुलता ब्लॉग पोस्ट लिखा था(https://ryanmadden.net/things-i-learned-at-google-design-docs/), और उसमें information density व अभ्यास के महत्व जैसी समानताएँ तथा कंपनियों के हिसाब से फर्क देखना दिलचस्प था। 'छोटे पैराग्राफ' वाली बात पर मैं थोड़ा अलग सोचता हूँ। छोटे पैराग्राफ तभी आते हैं जब जानकारी अच्छी तरह तराशी गई हो; सिर्फ लाइन ब्रेक बदल देने से मदद नहीं मिलती। मुझे लगता है कि 'Editing' वाला हिस्सा उस बुनियादी विचार को बेहतर समझाता है
• मैं एक प्रक्रिया अपनाता हूँ। चरण 1: जो भी मन में आए, उसे बिना क्रम के दस्तावेज़ में उड़ेल दो (चाहो तो voice dictation भी आज़मा सकते हो)। चरण 2: LLM(large language model) से संरचना और flow बनवाने की कोशिश करो। सच कहूँ तो इस चरण का आउटपुट फेंकना भी पड़ सकता है; यह सोच को लगातार सँवारने की प्रक्रिया है। चरण 3: LLM के परिणाम का संदर्भ लेकर, या बिल्कुल नया outline बनाकर पहला draft लिखो। चरण 4: शब्द कम करो, आसान शब्द चुनो, और जितना संभव हो उतना संक्षिप्त बनाओ। चरण 5: चरण 4 दोहराओ। LLM बिखरे हुए draft को संरचना देने वाले पुल की तरह काम करता है। LLM ने जो निकाला है उसे फेंक देने की तैयारी भी रखनी चाहिए। कम से कम 30% हमेशा घटाया जा सकता है। हर बार यह देखकर आश्चर्य होता है कि कम करते हुए भी अर्थ खोता नहीं
  • मुझे लगता है कि अपने लेख को फिर से edit करने की प्रक्रिया, पहली बार लिखने जितनी ही महत्वपूर्ण है। इसी दौरान पता चलता है कि मैंने निष्कर्ष कितनी जल्दी निकाल लिया था, या किन बातों पर विचार नहीं किया। लगता है बहुत से लोग लेखन को सोच को केंद्रित करने वाले उपकरण के रूप में पर्याप्त महत्व नहीं देते। कोड में भी यही बात लागू होती है। मान लो सिर्फ एक साधारण template ही लिखना हो, फिर भी test code लिखते समय अक्सर main code को बेहतर बनाने के विचार आ जाते हैं। लेकिन LLM इस तरह के गुणात्मक सुधार के अवसर नहीं दिखाता
  • यह विस्तार, संक्षेप, संपीड़न, फिर विस्तार, फिर संपीड़न—इसी का दोहराव है। जब कोई ठोस सवाल पूछता है तो फिर से विस्तार करना पड़ता है, और अंत में मज़े के लिए बिना दबाव वाला summary बनाने में LLM का उपयोग हो जाता है। मतलब हम सचमुच एक अंतहीन roller coaster पर सवार हैं
• मुझे लगता है कि मुझे और लिखना चाहिए। दस्तावेज़ संरचना के लिए जिन तरीकों को मैं प्रतिनिधि मानता हूँ, वे हैं B.O.O. और Good Strategy/Bad Strategy। B.O.O. का मतलब है Background, Objective, Overview—यानी यहाँ तक पहुँचने का प्रवाह क्या था, और क्या तथा कैसे बदलना है, इसे व्यवस्थित करना। Good Strategy/Bad Strategy एक किताब है जो diagnosis, guideline/constraints/requirements, और action से बनी है, और दस्तावेज़ संगठन के लिहाज़ से B.O.O. से मिलती-जुलती है। B.O.O. Google या छोटे संगठनों के सदस्यों के लिए अच्छी बैठती है, जबकि Good Strategy/Bad Strategy कहीं अधिक विविध आकार के संगठनों पर लागू हो सकती है, लेकिन उसके लिए अच्छा लिखने वाला लेखक चाहिए
• तकनीकी लेखन की कक्षा लेते समय, मुख्य बिंदु को स्पष्ट रूप से summarize करने की क्षमता में बहुत सुधार हुआ। ध्यान 'लाल पेन से काटने' वाले तरीके पर था (लिखो, काटो, फिर से लिखो), जो इस बात पर ज़ोर देता है कि कम से कम शब्दों में concept कैसे पहुँचाया जाए। यह प्रक्रिया कई चरणों में बँटी होती है, और अभ्यास के साथ आसान होती जाती है। मैं ऐसी क्षमता टीम के साथियों के साथ भी बाँटने की कोशिश करता हूँ, लेकिन हमेशा याद दिलाता हूँ कि यह नियमित अभ्यास से निखरने वाली skill है
• मुझे इस तरह लिखे गए दस्तावेज़ और यह पूरी लेखन संस्कृति बहुत पसंद है। लेकिन मैंने ऐसे मामले भी देखे हैं जहाँ यह तरीका उलटा असर करता है। इस शैली में निष्कर्ष तक पहुँचने के कारण और तर्क समझाना persuasive दस्तावेज़ों के लिए बहुत प्रभावी है। लेकिन हर बार ऐसी persuasion की ज़रूरत नहीं होती। कई बार निष्कर्ष सीधे शुरुआत में लिख देना पाठक के लिए, खासकर उन पाठकों के लिए जो लेखक पर भरोसा करते हैं, बेहतर होता है। बहुत बार पाठक तर्क की पूरी यात्रा से थकने के बजाय पहले मुख्य बात जानना चाहते हैं। निष्कर्ष पता चल जाने के बाद ही वे विस्तार से तर्क पढ़ना चाहेंगे
  • ऊपर summary और नीचे विस्तार व आधार देने वाली संरचना भी पूरी तरह ठीक है
• कभी-कभी मैं खुद ऐसे डिज़ाइन दस्तावेज़ लिखता हूँ जिन्हें शायद सिर्फ मैं ही पढ़ूँगा। फिर भी चीज़ों को लिखित रूप में छोड़ना अपने आप में बहुत शक्तिशाली लगता है। अगर वास्तविक उदाहरण वाले दस्तावेज़ मिल जाएँ तो बहुत मदद होगी; मैं अपनी दस्तावेज़ संरचना की तुलना दूसरों की अंतिम संरचना से करना चाहूँगा