फ़्लफ़ (अनावश्यक बातें)

• क्या फ़्लफ़ ट्रांज़िशन हटा दिए गए हैं? (“यह ध्यान देना महत्वपूर्ण है”, “उन्होंने ऐसा क्यों किया?”, “यहां बताया गया है कि हम इस समस्या को कैसे हल कर सकते हैं।”) कभी-कभी, प्रवाह के लिए इनकी आवश्यकता होती है, लेकिन अधिकांश को हटाया जा सकता है। “यह ध्यान देना महत्वपूर्ण है” तकनीकी लेखन में सबसे अधिक इस्तेमाल किया जाने वाला वाक्यांश है। इसका उपयोग न करें।
• यदि कोई चीज़ महत्वपूर्ण है, तो स्पष्ट करें कि वह महत्वपूर्ण क्यों है। आपका स्पष्टीकरण इतना सम्मोहक होना चाहिए कि यह स्पष्ट हो जाए कि विषय महत्वपूर्ण है।
• क्या कोई मामूली (trivial) जानकारी है जिसे हटाया जा सकता है?
• क्या ऐसे कोई दोहराए गए वाक्य हैं जो मूल विचारों पर ज़ोर नहीं देते हैं? मूल विचारों को अलग-अलग दृष्टिकोण से दोहराना ठीक है, लेकिन गैर-मूल विचारों को दोहराया नहीं जाना चाहिए।
• क्या कोई फ़्लफ़ शब्द या फ़्लफ़ वाक्य हैं?
• ऐसा कुछ भी लिखने से बचें जो प्रचारात्मक (promotional) लगे। आम तौर पर, निम्नलिखित शब्दों और वाक्यांशों का उपयोग नहीं किया जाना चाहिए क्योंकि वे व्यक्तिपरक (subjective) होते हैं और मापने योग्य, उपयोगी या कार्रवाई योग्य जानकारी नहीं देते हैं:
  • “novel” (नया/अनोखा)
  • “innovative” (अभिनव)
  • “unleash” (उन्मुक्त करना)
  • “breakthrough” (बड़ी उपलब्धि)
  • “game-changing” (गेम-चेंजिंग)
  • “pioneering” (अग्रणी)
  • “disruptive” (विघटनकारी)
  • “scalable” (स्केलेबल)
  • “empowering” (सशक्त बनाना)
  • “adoption” (एडॉप्शन/अपनाना)
  • “opens up possibilities” (संभावनाएं खोलता है)
  • “unparalleled” (अतुलनीय)
  • “creates opportunities” (अवसर पैदा करता है)
  • “transformative” (परिवर्तनकारी)
  • “unveiling” (अनावरण)
  • “visionary” (दूरदर्शी)
  • “groundbreaking” (अभूतपूर्व)
  • “has potential” (क्षमता है)
  • “spearhead” (नेतृत्व करना)
  • “esteemed” (सम्मानित)
  • “ambitious” (महत्वाकांक्षी)
  • “thriving” (फलने-फूलने वाला)
  • “cutting-edge” (अत्याधुनिक)
• बिक्री जैसी (sales-y) भाषा को हटा दें। यह पाठक के समय की बर्बादी है।

सम्मोहक उदाहरण (Compelling Examples)

• क्या लेख में उपयोगी और सम्मोहक उदाहरण जोड़ने से फायदा हो सकता है? एक सम्मोहक उदाहरण चरणों को दिखाए बिना एल्गोरिदम की व्याख्या करता है। उदाहरण के लिए: divWadUp(2,3) → 0.66667, divWadDown(2,3) → 0.66666
• जहाँ संभव हो, वास्तविक दुनिया के उदाहरण जोड़ें।
• जहाँ व्यावहारिक हो, डिज़ाइन निर्णयों के लिए ऐतिहासिक संदर्भ प्रदान करें।
• अमूर्त (Abstract) अवधारणाओं को स्पष्ट रूप से समझाने के लिए बहुत सारे उदाहरणों की आवश्यकता होती है। पर्याप्त उदाहरण दें ताकि पाठक अपने दिमाग में एक पैटर्न बना सके।

बेहतर शब्दावली

• क्या जानकारी खोए बिना किसी वाक्य को छोटा किया जा सकता है?
• क्या एक वाक्य को दो हिस्सों में बांटा जा सकता है?
• क्या वाक्य में उपवाक्यों (clauses) की संख्या कम की जा सकती है?

तथ्यों के लिए संदर्भ प्रदान करना

• क्या जानकारी प्रेरित (motivated) है (यानी मुझे परवाह क्यों करनी चाहिए?)?
• क्या ऐसे बहुत ही समान तथ्य हैं जिनसे लेखक समानता (analogy) स्थापित कर सकता है?
• क्या लेखक यह दर्शाता है कि प्रस्तुत तथ्य वर्तमान विषय से कैसे संबंधित है?

उद्धरण (Citations) और अन्य ट्यूटोरियल

• क्या लेख में कम से कम एक अनूठी जानकारी (unique insight) है, या आप सिर्फ वही दोहरा रहे हैं जो पहले से मौजूद है? अपने व्यक्तिगत लाभ के लिए अन्य लोगों के काम को सारांशित करना ठीक है, लेकिन इससे अन्य लोगों को मदद नहीं मिलती है। आप किसी कम-दस्तावेजीकृत (under-documented) समस्या से जितना अधिक संघर्ष करेंगे, अन्य पाठक आपको उतना ही अधिक धन्यवाद देंगे।
• यदि लेख कोई अन्य स्पष्टीकरण या उदाहरण उधार लेता है, तो क्या यह उसका उद्धरण (cite) देता है?

लेख का प्रवाह और हेडर्स

• क्या प्रस्तावना पाठक को बताती है कि लेख से क्या उम्मीद करनी है?
• क्या सूचना निर्भरताएं टोपोलॉजिकली सॉर्ट (topologically sorted) की गई हैं? यानी, कोई भी चर्चा जो पूर्व ज्ञान मानकर चलती है, वह पूर्व ज्ञान के स्पष्ट होने के बाद आनी चाहिए।
• क्या कोड या पिछली जानकारी को संदर्भित करने के लिए पाठकों को ऊपर-नीचे स्क्रॉल करने की आवश्यकता होती है? क्या पाठक बड़ी स्क्रीन पर ऊपर स्क्रॉल किए बिना निबंध को समझ सकते हैं?
• यदि चर्चा किए गए विषयों में कोई सर्कुलर डिपेंडेंसी है, तो स्पष्ट रूप से बताएं कि आपको कहाँ लगता है कि पाठक भ्रमित हो सकता है और उन्हें बाद के अनुभाग की प्रतीक्षा करने के लिए कहें।
• यदि पाठक केवल हेडर्स को सरसरी तौर पर पढ़ते हैं, तो क्या उन्हें फिर भी इसका अच्छा अंदाज़ा हो जाएगा कि क्या हो रहा है? खराब हेडर्स में “Example”, “Line 20” शामिल हैं।
• क्या हेडर्स एक पदानुक्रम (hierarchy) का पालन करते हैं?
• क्या ऐसे कोई टॉपिक ट्रांज़िशन हैं जिनमें हेडर की कमी है?
• क्या पैराग्राफ उचित रूप से विभाजित हैं, और क्या यह टेक्स्ट की एक बड़ी दीवार जैसा तो नहीं लग रहा?

लक्षित दर्शक (Target audience)

• क्या जटिलता का स्तर/पाठक का स्तर सुसंगत (consistent) रहता है?
• यह मत मानिए कि पाठक को एक पल रीएन्ट्रेंसी (reentrancy) सिखाने की आवश्यकता है, और फिर अगले ही पल उनसे यह समझने की अपेक्षा करें कि Ethereum ने Blake hash precompile क्यों जोड़ा। यदि आप निश्चित नहीं हैं, तो अतीत में एक निश्चित समय पर मौजूद खुद को ध्यान में रखकर लिखने का प्रयास करें, यानी 3 महीने पहले, 6 महीने पहले, एक साल पहले, आदि।

लेख की सामग्री

• क्या विषय से हटकर (off-topic) जानकारी हटा दी गई है या किसी अन्य लेख के लिए टाल दी गई है?
• “दिलचस्प लेकिन अप्रासंगिक बातों” (interesting tangents) पर जाने से बचें, जब तक कि वे मनोरंजक या सीधे तौर पर उपयोगी न हों।
• लेख पढ़ने के बाद, क्या ऐसा लगता है कि कोई प्रमुख विचार या स्पष्टीकरण गायब है?
• सभी विचारों का आपस में जुड़ना ज़रूरी है। विषय से हटकर कोई जानकारी या अकारण (unmotivated) उदाहरण नहीं होना चाहिए। क्या लेख बताता है कि चर्चा किया गया प्रत्येक विषय एक-दूसरे से कैसे संबंधित है?

कोड ब्लॉक और गणित के सूत्र

• यदि लागू हो, तो क्या कोड को कॉपी और पेस्ट करना आसान है?

• यदि कोड को कॉपी और पेस्ट करने के लिए दिया गया है, तो क्या पाठक को कोड को ठीक से चलाने के लिए आवश्यक पूर्व-शर्तों (prerequisites) के बारे में सूचित किया गया है?

• यदि कोड कॉपी और पेस्ट करने के लिए नहीं है, तो आमतौर पर स्क्रीनशॉट बेहतर होगा।

• क्या कोड के स्क्रीनशॉट पढ़ने में आसान हैं? क्या उनमें कम सफेद स्थान (white space) और बड़े फ़ॉन्ट हैं?

• यदि प्रोग्राम के निष्पादन (execution) से कोई अपेक्षित आउटपुट मिलता है, तो क्या उसका स्क्रीनशॉट मौजूद है?

• क्या कोड के स्पष्टीकरण एक अंतर्ज्ञान (intuition) देते हैं या प्रतीकात्मक रूप से निष्पादित (symbolically execute) होते हैं? कोड को लाइन-दर-लाइन मत समझाइए। पाठक को यह समझने में मदद करने का प्रयास करें कि क्या हो रहा है ताकि जब वे कोड देखें, तो “सब कुछ समझ में आ जाए।”

• यदि आपको किसी लाइन नंबर का संदर्भ देने की आवश्यकता है, तो कोड का स्क्रीनशॉट लें और ध्यान आकर्षित करने के लिए छवि पर चित्र बनाएं (draw करें)। इसे एक उदाहरण के रूप में उपयोग करें: https://www.rareskills.io/post/uniswap-v2-mint-and-burn।

• क्या बड़े कोड ब्लॉक या फ़ार्मुलों में महत्वपूर्ण हिस्सों को इंगित करने के लिए विज़ुअल संकेत (visual cues) हैं?

• आप जहां पाठक का ध्यान आकर्षित करना चाहते हैं, वहां ध्यान खींचने के लिए ALL CAPS COMMENTS (बड़े अक्षरों में टिप्पणियों) का उपयोग करें। बेहतर होगा कि आप स्क्रीनशॉट का उपयोग करें और कोड को एनोटेट (annotate) करें।

• लंबे बीजगणितीय (algebraic) व्युत्पन्नों (derivations) को छोड़ना (skip) या सरसरी तौर पर पढ़ना (skim) आसान बनाएं।

आरेख (Diagrams) और चित्र

• एक तस्वीर हजार शब्दों के बराबर होती है; क्या सही तस्वीरें शामिल की गई हैं?
• क्या चित्रों में कम से कम खाली जगह (empty space) है (ये मोबाइल पर सामग्री को पढ़ना मुश्किल बनाते हैं)?
• क्या चित्रों को एक अनुमानित तरीके से पढ़ा जा सकता है (बाएं-से-दाएं या ऊपर-से-नीचे)?
• चित्रों में ऐसे फ़ॉन्ट का उपयोग करें जो पढ़ने में आसान हो, और सुनिश्चित करें कि वे मोबाइल डिवाइस पर आसानी से पढ़े जा सकें।
• प्रकाशित होने पर चित्रों में alt-text होना चाहिए।
• यदि कोई कार्य किसी दृश्य (visual) चीज़ का वर्णन कर रहा है, तो उसे विज़ुअलाइज़ किया जाना चाहिए।

कॉग्निटिव लोड (Cognitive load) कम करें

• पाठक को अपनी शॉर्ट-टर्म मेमोरी में जितनी जानकारी रखने की आवश्यकता है, उसे कम से कम करें — यदि जानकारी पाठक के लिए नई होने की उम्मीद है, तो आवश्यकता पड़ने पर पिछली जानकारी को दोहराएं।
• पाठक से मन ही मन मुद्रा बदलने या गणित हल करवाने से बचें। “token A” जैसी अमूर्त मुद्राओं (abstract currencies) से बचें और डॉलर मूल्य में बात करें।
  • क्या पाठक के लिए कॉग्निटिव लोड को कम करने के लिए कुछ और किया जा सकता है?
• स्पष्ट संख्यात्मक उदाहरणों का उपयोग करें। यह तुरंत स्पष्ट नहीं होता है कि 6 गुणा 68 का मतलब 408 है, लेकिन यह तुरंत स्पष्ट है कि 6 गुणा 4 का मतलब 24 है। उदाहरणों में मानों (values) के साथ तब तक प्रयोग करना उचित है जब तक कि प्रस्तुत किए गए सभी मान स्पष्ट संख्यात्मक संबंध न बन जाएं।
• वेरिएबल्स और अन्य कोड ऑब्जेक्ट्स को code formatted (कोड फ़ॉर्मेटेड) होना चाहिए।
• जब तक आप उन विषयों के अनुवर्ती (follow-on) के रूप में नहीं लिख रहे हैं, तब तक पाठकों को पूर्व-शर्तें (prerequisite) सीखने के लिए अन्य पेजों पर भेजने से बचें। यह पाठक को संदर्भ (context) बदलने के लिए मजबूर करता है। लेख के अंदर ही प्रमुख विचारों को सारांशित करें।
• किसी फ़ोल्डर का संदर्भ देते समय, उसके बाद एक फ़ॉरवर्ड स्लैश जोड़ें। उदाहरण के लिए " src/ डायरेक्टरी में हम देखते हैं कि…"

काउंटरफैक्टुअल (Counterfactuals) का उपयोग करना और सवालों के जवाब देना

• काम न करने वाले कोड के उदाहरण देना कभी-कभी मददगार हो सकता है यदि यह स्पष्ट करता है कि कोड काम क्यों नहीं करता है।
• क्या किसी विषय को उसी चीज़ को पूरा करने के वैकल्पिक तरीके को समझाने से लाभ हो सकता है?
• क्या किसी बात ने ऐसे सवाल खड़े किए जिनका उत्तर नहीं दिया गया?
• क्या किसी विषय का स्पष्टीकरण अधूरा है?
• कभी-कभी, विषयों को स्वयं समझाने के बजाय उनके आस-पास के विषयों को समझाकर बेहतर तरीके से समझाया जा सकता है। उदाहरण के लिए, फ्लोटिंग पॉइंट और पूर्णांक (integers) को समझाए बिना अलग से “fixed point numbers” को प्रेरित (motivate) करना कठिन है।
• “यह ऐसा क्यों है और किसी अन्य तरीके से क्यों नहीं” जैसे सवालों के जवाब देने के अवसरों का लाभ उठाएं।

शब्दावली और परिभाषाएं

• पाठक को एक साथ बहुत सारी जटिल (non-trivial) परिभाषाएं देने से बचें। इससे कॉग्निटिव लोड बढ़ता है।
• नई शब्दावली पेश करते समय, इसे संक्षेप में परिभाषित करें, भले ही आप बाद में इसे विस्तार से समझाएं। पाठक को अपने दिमाग में एक ऐसा नया शब्द रखने के लिए मजबूर करना जिसे वे नहीं समझते हैं, कॉग्निटिव लोड को बढ़ाता है।
• यदि शब्दावली पूरी तरह से सामान्य नहीं है, तो इसे एक सब-हेडर बनाना मददगार हो सकता है। इस तरह, यदि पाठक भूल जाता है, तो वह पीछे की ओर सरसरी नज़र डालकर इसे आसानी से ढूंढ सकता है।
• प्रमुख शब्दों और परिभाषाओं के लिए, पर्यायवाची शब्दों (synonyms) से बचें। एक ही शब्द का बार-बार उपयोग करें ताकि पाठक को यह स्पष्ट हो जाए कि आप किसका उल्लेख कर रहे हैं।

एक समीक्षक (Reviewer) के रूप में अच्छा फीडबैक कैसे दें

• उन क्षेत्रों को इंगित करें जो स्पष्ट नहीं हैं, लेकिन जहां आपको लगता है कि आप लेखक को समझ रहे हैं, अपने शब्दों में लिखें कि आपको क्या लगता है कि लेखक क्या कह रहा है। इससे लेखक को इस बात का फीडबैक मिलेगा कि पाठक उनके शब्दों की व्याख्या कैसे कर रहा है।
• यदि कोई उदाहरण सम्मोहक या मददगार है, तो उसे इंगित करें ताकि लेखक उसे बाद में डिलीट न करे।
• यदि आप कुछ समझते हैं लेकिन इसके लिए संघर्ष करना पड़ता है (यानी इसे कई बार पढ़ना पड़ता है), तो इसे इंगित करें। लक्ष्य चीजों को पढ़ने में आसान बनाना है। “मुझे समझने में संघर्ष करना पड़ा” किसी अक्षमता (incompetence) की स्वीकृति नहीं है।
• लेख को ज़ोर से पढ़ें। आप इस तरह से अधिक कमियों को पकड़ पाएंगे।
• समीक्षा प्रक्रिया के शुरुआत में शब्दावली या वर्तनी (spelling) के बारे में प्रतिक्रिया न दें। सबसे पहले उच्च-स्तरीय (high-level) फीडबैक पर ध्यान दें। आदर्श रूप से, फीडबैक का पहला दौर इतना उच्च-स्तरीय होना चाहिए कि यह सीधे दस्तावेज़ पर टिप्पणी न करे।
• Grammarly या चैटबॉट जैसे टूल से मिले फीडबैक को दोहराना तब तक बेकार है जब तक कि लेखन प्रक्रिया बिल्कुल अंत में न हो। एक पाठक के रूप में आपकी प्रतिक्रिया पर ध्यान दें।
• विषय पर तुरंत Google खोज करें और किसी चैटबॉट से उसी विषय पर एक लेख लिखने के लिए कहें। यदि संबंधित लेख कोई नई जानकारी (fresh insights) प्रदान नहीं करता है, तो लेखक को बताएं। यह सबसे मूल्यवान फीडबैक है जो आप दे सकते हैं।

तकनीकी लेख तैयार करना

• लिख लें कि आपके लक्षित दर्शक (target audience) पहले से क्या जानते हैं।
• लिख लें कि वे आपका लेख क्यों पढ़ना चाहते हैं।
• उन प्रमुख विचारों को लिखें जिन्हें आप कवर करना चाहते हैं।
• विषय पर मौजूद किसी भी लेख की सूची बनाएं और बताएं कि आपको क्यों लगता है कि आपका लेख अतिरिक्त मूल्य (added value) प्रदान करेगा।
• उन अवधारणाओं को लिखें जो आपके लिए या उन लोगों के लिए विशेष रूप से भ्रमित करने वाली थीं जिन्हें आपने विषय समझाया है।
• उन चित्रों और आरेखों (diagrams) की सूची बनाएं जिन्हें आप अपने लेखन की योजना बनाने के लिए बनाएंगे।

मूल रूप से 25 मार्च, 2024 को प्रकाशित