सॉफ़्टवेयर ट्यूटोरियल लिखने के नियम

 (refactoringenglish.com)
70 पॉइंट द्वारा xguru 2025-01-15 | 11 टिप्पणियां | WhatsApp पर शेयर करें
  • ज़्यादातर सॉफ़्टवेयर ट्यूटोरियल महत्वपूर्ण विवरण छोड़ देते हैं या ऐसी छिपी हुई मान्यताएँ शामिल करते हैं जो पाठक की अपेक्षाओं से मेल नहीं खातीं, जिससे पाठक प्रक्रिया को दोहरा नहीं पाता
  • कुछ सरल नियमों का पालन करें तो बेहतरीन ट्यूटोरियल लिखना सोच से ज़्यादा आसान है

नियम

  1. शुरुआती लोगों के लिए लिखें
  2. ऐसा शीर्षक लिखें जो स्पष्ट परिणाम का वादा करे
  3. परिचय में लक्ष्य समझाएँ
  4. अंतिम परिणाम पहले दिखाएँ
  5. कॉपी/पेस्ट किए जा सकने वाले code snippets लिखें
  6. commands में लंबे flags का उपयोग करें
  7. user-defined values और reusable logic को अलग रखें
  8. पाठक की मेहनत कम करें
  9. code को हमेशा working state में रखें
  10. केवल एक ही विषय सिखाएँ
  11. सजावट से ज़्यादा स्पष्टता को प्राथमिकता दें
  12. dependencies को न्यूनतम रखें
  13. file names स्पष्ट रूप से बताएं
  14. consistent और वर्णनात्मक headings का उपयोग करें
  15. साबित करें कि solution काम करता है
  16. complete example को लिंक करें

शुरुआती लोगों के लिए लिखें

  • ट्यूटोरियल में सबसे आम गलती यह है कि शुरुआती स्तर की अवधारणाओं को expert-level terminology में समझाया जाता है। अधिकांश लोग जो ट्यूटोरियल खोजते हैं, वे शुरुआती होते हैं।
    • हो सकता है वे programming में शुरुआती न हों, लेकिन जिस domain को सीखना चाहते हैं उसमें वे शुरुआती होते हैं
  • शुरुआती लोगों को ध्यान में रखकर लिखें और expert-level terms के उपयोग से बचें
  • कठिन शब्दों से बचें और ऐसी सरल भाषा में लिखें जिसे पाठक समझ सके
  • उदाहरण के लिए, React ट्यूटोरियल में "JSX transpilation" की जगह "React का उपयोग करके एक सरल web page बनाना" जैसे वर्णन दें

ऐसा शीर्षक लिखें जो स्पष्ट परिणाम का वादा करे

  • शीर्षक को यह साफ़ तौर पर बताना चाहिए कि पाठक ट्यूटोरियल से क्या सीख सकेगा
  • अस्पष्ट या धुंधले शीर्षकों से बचें, और अपेक्षित परिणाम को स्पष्ट रूप से समझाएँ
    • उदाहरण: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

परिचय में लक्ष्य समझाएँ

  • जब पाठक ट्यूटोरियल पर क्लिक करता है, तो इसका मतलब है कि उसे आपकी बात में रुचि है। लेकिन उसे आगे पढ़ते रहने के लिए आपको मनाना होगा
  • पाठक दो बातें जानना चाहता है
    • क्या मुझे इस तकनीक में रुचि लेनी चाहिए?
    • अगर रुचि है, तो क्या यह ट्यूटोरियल मेरे लिए सही है?
  • परिचय में तकनीक के महत्व और ट्यूटोरियल की उपयोगिता को संक्षेप में समझाएँ
  • पाठक की रुचि बनाए रखने के लिए उपयोगी जानकारी दें और धुंधले वर्णन से बचें
    • उदाहरण: Docker ट्यूटोरियल में साफ़ बताएं कि Docker कौन-सी समस्या हल करता है और अपेक्षित परिणाम क्या होगा

अंतिम परिणाम पहले दिखाएँ

  • जितना जल्दी हो सके, पाठक को वह demo या screenshot दिखाएँ जो वह ट्यूटोरियल के माध्यम से बनाएगा
    • ट्यूटोरियल की शुरुआत में अंतिम परिणाम दिखाने से लक्ष्य स्पष्ट हो जाता है
  • उदाहरण: अंतिम product का screenshot, UI, या काम करने का example दें

कॉपी/पेस्ट किए जा सकने वाले code snippets लिखें

  • इस तरह लिखें कि पाठक code को आसानी से कॉपी करके editor या terminal में पेस्ट कर सके और चला सके
  • terminal prompt character जैसे $ जैसी अनावश्यक चीज़ें हटा दें
  • commands को सरल बनाने के लिए non-interactive flags का उपयोग करें, और failure होने पर रुकने के लिए && का उपयोग करें

commands में लंबे flags का उपयोग करें

  • commands में छोटे flags की जगह ऐसे लंबे flags का उपयोग करें जिनका अर्थ स्पष्ट हो, ताकि शुरुआती लोग भी आसानी से समझ सकें
    • -r की बजाय --recursive

user-defined values और reusable logic को अलग रखें

  • code में जिन values को उपयोगकर्ता को बदलना है और जिन code को नहीं बदलना चाहिए, उन्हें स्पष्ट रूप से अलग रखें
  • environment variables का उपयोग करके custom values को परिभाषित करें और code की readability बढ़ाएँ

पाठक की मेहनत कम करें

  • अगर आप चाहते हैं कि पाठक ट्यूटोरियल पसंद करे, तो उसके समय का सम्मान करें
  • उबाऊ manual काम की जगह command snippets दें
    • उदाहरण: file को हाथ से संपादित कराने की बजाय command से समस्या हल करें

code को हमेशा working state में रखें

  • example code हमेशा चलने योग्य होना चाहिए, और बीच के चरणों में भी काम करता रहना चाहिए
  • गलत code या न चलने वाले examples पाठक को भ्रमित करते हैं

केवल एक ही विषय सिखाएँ

  • ट्यूटोरियल को एक ही विषय के इर्द-गिर्द लिखें और असंबंधित तकनीकों को साथ न मिलाएँ
  • उदाहरण के लिए, search feature समझाने वाले ट्यूटोरियल में अनावश्यक AI तकनीक न जोड़ें

सजावट से ज़्यादा स्पष्टता को प्राथमिकता दें

  • पाठक इस बात की परवाह नहीं करता कि toy application सुंदर दिखती है या नहीं
  • अनावश्यक CSS या design elements को न्यूनतम रखें और मुख्य अवधारणा पर ध्यान दें
  • जटिल examples की बजाय सरल code से अवधारणा को स्पष्ट करें

dependencies को न्यूनतम रखें

  • पाठक को install करनी पड़ने वाली dependencies को कम से कम रखें ताकि ट्यूटोरियल अधिक सुलभ बने
  • आवश्यक dependencies को स्पष्ट रूप से बताएं और specific versions का उल्लेख करें

file names स्पष्ट रूप से बताएं

  • पाठक को ठीक-ठीक बताएं कि कौन-सा file path और कौन-सी सामग्री बदलनी है
  • उदाहरण के लिए, "config file में setting जोड़ें" कहने की बजाय पूरा file path दें और ठीक किस line को edit करना है, इसका ठोस code उदाहरण दें

consistent और वर्णनात्मक headings का उपयोग करें

  • ऐसे structured headings का उपयोग करें जिससे पाठक ट्यूटोरियल को आसानी से scan कर सके
  • headings के माध्यम से ट्यूटोरियल को व्यवस्थित करें और उन्हें इस तरह लिखें कि वे तार्किक संरचना को दर्शाएँ
  • headings का format, दृष्टिकोण, और tense एक जैसा रखें

साबित करें कि solution काम करता है

  • अगर ट्यूटोरियल किसी tool की installation या कई components के integration को सिखाता है, तो दिखाएँ कि परिणाम का उपयोग कैसे किया जाए
    • install किए गए और integrated tools के काम करने का परिणाम पाठक को दृश्य रूप में दिखाएँ
  • उदाहरण के लिए, nginx success page दिखाएँ और URL के ज़रिए सत्यापित करने का तरीका दें

complete example को लिंक करें

  • ऐसा repository लिंक करें जिसमें ट्यूटोरियल का पूरा code शामिल हो, ताकि पूरा flow समझा जा सके
  • हर चरण के code को अलग-अलग git branches में बाँटें ताकि पाठक हर step का अनुसरण कर सके

संबंधित पढ़ाई

11 टिप्पणियां

 
godogi7 2025-02-12

संदर्भ के लिए
 
wedding 2025-01-16

ऐसी चीज़ों को याद रखो!
 
ilikeall 2025-01-16

अच्छा लेख है।
 
halfenif 2025-01-16

हाल ही में मैंने dagster के ट्यूटोरियल्स को फॉलो करके देखा। लगा कि यह काफ़ी अच्छी तरह से बनाया गया है।

https://courses.dagster.io/
 
aer0700 2025-01-16

मैंने Dagster का ट्यूटोरियल पूरा देखा, और वह बहुत अच्छा लगा।
Django ट्यूटोरियल की सामग्री तो बढ़िया है, लेकिन वह बहुत लंबा है, इसलिए मुझे उतना पसंद नहीं है। अच्छा होता अगर उसे थोड़ा हिस्सों में बाँटा गया होता।
 
savvykang 2025-01-16

अच्छी तरह बनाए गए tutorial के एक उदाहरण के रूप में Django भी है https://docs.djangoproject.com/en/5.1/intro/tutorial01/
 
jhj0517 2025-01-16

सरल भाषा का उपयोग करें और अंतिम परिणाम सबसे पहले दिखाएँ।
 
aer0700 2025-01-15

फ़्रेमवर्क के बुनियादी इस्तेमाल का उबाऊ तरीका दिखाने के बजाय,
कभी-कभी ऐसे ट्यूटोरियल दस्तावेज़ होते हैं जो यह दिखाना चाहते हैं कि यह फ़्रेमवर्क कितना शानदार है।
मैंने Get started खोला, लेकिन अगर जिस चीज़ को बुनियादी उपयोग का ट्यूटोरियल कहा गया है वह 10 पेज का दस्तावेज़ निकले, तो यह मुझे बिल्कुल पसंद नहीं आता।
 
beenzinozino 2025-01-16

सभी लोग कमाल के हैं...