उदाहरण ही सबसे बेहतरीन डॉक्यूमेंटेशन हैं

 (rakhim.exotext.com)
38 पॉइंट द्वारा GN⁺ 2025-10-11 | 8 टिप्पणियां | WhatsApp पर शेयर करें
  • जब डेवलपर डॉक्यूमेंटेशन खोजते हैं, तो 95% मामलों में सिर्फ़ एक आसान उदाहरण ही काफ़ी होता है, लेकिन आधिकारिक स्रोतों में उदाहरण मिलना केवल 5% मामलों में ही संभव होता है
  • आधिकारिक तकनीकी डॉक्यूमेंटेशन आम तौर पर उस ecosystem में गहराई से डूबे लोगों को ध्यान में रखकर लिखी जाती है, इसलिए कई projects और languages के बीच काम करने वाले डेवलपर्स के लिए context को फिर से बनाने में काफ़ी mental energy लगती है
  • Python के max() फ़ंक्शन की docs देखें तो फ़ंक्शन definition syntax और concepts को समझने के लिए काफ़ी पूर्वज्ञान चाहिए, लेकिन 5 पंक्तियों के आसान उदाहरण से इसे तुरंत समझा जा सकता है
  • Clojure community की clojuredocs.org, user-contributed examples के ज़रिए practical documentation देती है, और related functions तक शामिल करके वास्तविक उपयोगिता बढ़ाने वाला एक आदर्श उदाहरण है
  • बड़े software projects में भी चार तरह की documentation उपलब्ध होना दुर्लभ है, इसलिए डेवलपर्स tutorials ढूँढते हैं; ऐसा इसलिए नहीं कि उन्हें मार्गदर्शन चाहिए, बल्कि क्योंकि उन्हें उदाहरण चाहिए

डॉक्यूमेंटेशन खोजते समय उदाहरणों का महत्व

  • जब डेवलपर डॉक्यूमेंटेशन ढूँढते हैं, तो 95% मामलों में सिर्फ़ एक ही उदाहरण काफ़ी होता है
  • लेकिन आधिकारिक स्रोत में उदाहरण मिलना केवल 5% मामलों में ही संभव है
  • ज़्यादातर आधिकारिक तकनीकी डॉक्यूमेंटेशन ecosystem में गहराई से शामिल लोगों को मूल पाठक मानकर लिखी जाती है
  • कई डेवलपर्स को रोज़मर्रा में कई "दुनियाओं" को अपने दिमाग़ में एक साथ संभालना पड़ता है
    • projects, languages, frameworks के बीच लगातार स्विच करना पड़ता है
    • context को फिर से बनाना और स्थिति को समझने में काफ़ी मानसिक ऊर्जा खर्च होती है

Python docs का केस विश्लेषण

  • Python 3 docs में max() फ़ंक्शन का उदाहरण
    • max(iterable, /, *, key=None): सबसे बड़ा item लौटाता है
    • इसके बाद 5 छोटे paragraphs में व्याख्या जारी रहती है
  • इस documentation को समझने के लिए जो Python ज्ञान होना चाहिए
    • फ़ंक्शन definition में * का अर्थ
    • फ़ंक्शन definition में / का अर्थ
    • "positional-only parameter separator" की अवधारणा
    • iterable की अवधारणा
    • keyword-only arguments की अवधारणा
    • key parameter का सामान्य अर्थ
  • टेक्स्ट पढ़कर ही यह समझा जा सकता है कि कौन-सी values देनी हैं और फ़ंक्शन को वास्तव में कैसे call करना है

आसान उदाहरणों का प्रभाव

  • यह मानना होगा कि conciseness के लिए महत्वपूर्ण विवरण हमेशा छोड़े नहीं जा सकते
  • लेकिन बहुत से डेवलपर्स इस पेज पर इसलिए आते हैं क्योंकि वे बस यह जल्दी से देखना चाहते हैं कि max फ़ंक्शन में custom sorting function (key) कैसे देना है
  • अगर नीचे जैसे उदाहरण हों, तो ज़रूरी जानकारी तुरंत मिल सकती है 
    max(4, 6) # → 6  
max([1, 2, 3]) # → 3  
max(['x', 'y', 'abc'], key=len) # → 'abc'  
max([]) # ValueError: max() arg is an empty sequence  
max([], default=5) # → 5
  • उदाहरणों के ज़रिए इसे आसान और सहज रूप से समझा जा सकता है

Clojure community का आदर्श उदाहरण

  • clojuredocs.org, Clojure community पर आधारित project है
    • users built-in functions के लिए उदाहरण योगदान करते हैं
    • रोज़मर्रा की coding में यह एक अनिवार्य resource है
  • उदाहरण पेज: into, spit, map आदि देखें
  • उदाहरणों की विशेषताएँ
    • सिर्फ़ उस फ़ंक्शन तक सीमित नहीं, बल्कि related functions भी शामिल होते हैं
    • इससे वास्तविक उपयोगिता और practicality बढ़ती है

मौजूदा documentation की सीमाएँ

  • बड़े software projects में भी चार प्रकार की documentation उपलब्ध होना दुर्लभ है
  • "Documentation" लिंक पर क्लिक करने में हिचकिचाहट होने का कारण
    • ज़्यादातर यह संक्षिप्त और पढ़ने में कठिन auto-generated API references होती हैं
  • डेवलपर्स के tutorials खोजने का असली कारण
    • उन्हें मार्गदर्शन नहीं, उदाहरण चाहिए होते हैं
    • tutorials ज़्यादा उपयोगी लगते हैं क्योंकि उनमें examples शामिल होते हैं

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

8 टिप्पणियां

 
sonnet 2025-10-12

ईमानदारी से कहूं तो मुझे लगता है कि यह बात मुख्य रूप से Java और Python पर लागू होती है। यह ऐसा ecosystem भी है जहाँ language chauvinism या paradigm के हिसाब से अलग-थलग पड़ी culture काफ़ी मज़बूत होती है.
Python को आधार मानें तो बात ठीक बैठती है, लेकिन अलग-अलग भाषाएँ पढ़ते-पढ़ते यह 5% वाला हिस्सा काफ़ी बढ़ा-चढ़ाकर कहा गया सा लगता है।
 
kuber 2025-10-12

कोड ही असली documentation है, तो Go की दुनिया में आइए~
हम तो README न हो तब भी test code देखकर development करते हैं
 
pjtco 2025-10-11

मुझे लगा था सिर्फ़ मैं ही इतना धीमा हूँ कि official docs समझ नहीं पाता/पाती lol
सच में, बस example दे do और थोड़ा-सा explanation कर दो, तो तुरंत समझ आ जाता है.....
 
nemorize 2025-10-11

PHP शायद इसका सबसे अच्छा और सबसे खराब, दोनों तरह का उदाहरण होगा।

ऑफिशियल documentation में user-contributed content अपलोड किया जा सकता है, इसलिए तरह-तरह के code examples देखे जा सकते हैं — इस मायने में यह एक अच्छा उदाहरण है,

...लेकिन PHP में built-in functions के subtle BC issues बहुत हैं, और जो example contributions हैं वे भी ज़्यादातर बहुत पुराने ज़माने के versions के हैं, इसलिए उनमें ऐसी चीज़ें मिली-जुली रहती हैं जो असली behavior से थोड़ा अलग होती हैं, और इससे बस confusion ही बढ़ता है... lol... heh...
 
savvykang 2025-10-11

पुराने iOS या Cocoa डेवलपमेंट दस्तावेज़ों को देखें तो उनमें अलग से use case सेक्शन होता था; क्या वही सही documentation तरीका नहीं है? उदाहरण, function signature, और behavior का विवरण—सब कुछ ज़रूरी है।
 
aer0700 2025-10-11

उदाहरण ही सबसे बेहतरीन documentation हैं

पहले official docs की कमी Stack Overflow और Google खोज पूरी कर देते थे, लेकिन आजकल लगता है कि यह कमी LLM पूरा कर रहा है।
 
GN⁺ 2025-10-11
Hacker News राय

  • पुराने Python की सबसे अच्छी बातों में से एक यह थी कि लाइब्रेरी डॉक्यूमेंटेशन खोलते ही फ़ंक्शन के arguments और return values साफ़-साफ़ व्यवस्थित मिलते थे। आजकल कई JavaScript या Python लाइब्रेरी के docs सिर्फ examples देकर छोड़ देते हैं, जो खलता है। जल्दी कुछ बनाना हो तो examples अच्छे हैं, लेकिन bug ठीक करने या लाइब्रेरी सीखने के लिए argument values की व्याख्या ज़रूरी है। examples bonus हों तो अच्छा है, लेकिन वे सब कुछ नहीं होने चाहिए

    • असल में आपको type definitions चाहिए। type definitions अच्छे documentation का काम करती हैं। type system के tools पहले से ही बहुत-सी जानकारी editor या IDE में सीधे दिखा देते हैं, इसलिए अलग से docs ढूँढ़कर पढ़ने की ज़रूरत कम हो गई है। आजकल example-केंद्रित docs बढ़ने की वजह भी workflow में यही बदलाव है। जो जानकारी type tools दे ही देंगे, उसे docs में दोहराने की ज़रूरत नहीं समझी जाती। मैं docs देखते समय detailed arguments से ज़्यादा इस बात में दिलचस्पी रखता हूँ कि "यह tool किस समस्या को हल कर सकता है?" examples यह दिखाने में बेहतरीन हैं। जब कोई specific problem हल करनी हो, examples देखकर जल्दी समझ आ जाता है कि tool काम आएगा या नहीं। --- अगर type system है, तो मैं पहले examples देखना चाहूँगा। अगर type system नहीं है, तो 1) यह निराशाजनक है। 2) पहले examples, फिर detailed argument/return/data structure की व्याख्या चाहिए

    • अच्छे docs में दोनों चाहिए। पहले details समझाई जाएँ, फिर अलग-अलग examples दिए जाएँ ताकि बात verify की जा सके। कभी-कभी examples ही काफ़ी हो सकते हैं, लेकिन जब options के combinations बहुत ज़्यादा हों, तो सब कुछ examples में दिखाना लगभग असंभव होता है। इसलिए पहले हर option की explanation दें, फिर जितने हो सकें उतने विविध cases के examples तैयार करें ताकि पाठक उन्हें अपने हिसाब से लागू कर सके। और अच्छे docs बनाना बहुत कठिन है, आजकल तो वे सचमुच बहुत कम दिखते हैं

    • मैं पूरी तरह सहमत नहीं हूँ। Javadoc-स्टाइल docs, types और inline docstring पर आधारित programming documentation हैं। उनका होना ज़रूरी है, लेकिन उसके लिए वेब पर जाने के बजाय code को सीधे देखना ज़्यादा असरदार है। examples या QuickStart जैसी guides ज़रूर चाहिए। वही लाइब्रेरी की entry barrier कम करती हैं। सिर्फ code देखकर API का इस्तेमाल समझना आसान नहीं होता। पहले कई Java libraries सिर्फ Javadoc देती थीं, और इस्तेमाल कैसे करना है यह न समझ पाने का अनुभव काफ़ी खराब था

    • मेरी राय में अच्छे comments वाले examples सबसे बेहतरीन होते हैं। लेकिन वे पारंपरिक documentation की जगह नहीं ले सकते

    • क्या आपने कभी सोचा है कि दूसरे लोगों का learning style आपसे अलग हो सकता है? मुझे समझ नहीं आता कि examples को documentation का हिस्सा मानने में इतनी हिचक क्यों है। examples कई तरह की situations में context switching का friction कम करते हैं

  • Unix man pages को भी examples की सख़्त ज़रूरत है। वे अक्सर सिर्फ उन लोगों के लिए reference की तरह लिखी जाती हैं जो tool पहले से अच्छी तरह जानते हों, इसलिए beginners के लिए लगभग बेकार होती हैं। अच्छे docs में दोनों चीज़ें होनी चाहिए

    • पूरी तरह सहमत। मैं सभी man page लिखने वालों को याद दिलाना चाहूँगा कि conventional section EXAMPLE नाम से मौजूद है। man(1) आधिकारिक दस्तावेज़ देखना उपयोगी होगा

    • मुझे ऐसा मुद्दा कभी महसूस नहीं हुआ। मैं पहले कुछ code लिखकर commands और terms सीखता हूँ, फिर error return codes, उनके कारण, और parameters के अर्थ एक-एक करके देखता हूँ। अगर documentation पूरी हो, तो examples के बिना भी काफ़ी है। लेकिन बिना किसी explanation के सिर्फ examples देना सचमुच सबसे बुरा है। parameters क्या हैं, उनका मतलब क्या है, यह तक न बताया जाए तो उसे documentation कैसे कहेंगे?

    • यह जानकर अच्छा लगा कि Stack Overflow ने भी कभी ऐसा ही प्रयास किया था। Stack Overflow Documentation नाम से यह 2016 से 2017 तक beta में चला था। इसका लक्ष्य example-केंद्रित docs बनाना था, लेकिन यह बंद हो गया। फिर भी community द्वारा छोड़ा गया content अब भी CC BY-SA के तहत उपलब्ध है

    • cheat.sh देखिए। मैं इसे script में सीधे curl cheat.sh/"$1" से इस्तेमाल करता हूँ

    • मुझे हमेशा हैरानी होती है कि काफ़ी सारे man pages में examples होते भी हैं। फिर भी उन्हें और ज़्यादा समग्र रूप से बेहतर बनाने की गुंजाइश है

  • examples सिर्फ beginners या कभी-कभार इस्तेमाल करने वालों के लिए अच्छे नहीं हैं। अनुभवी users को भी औपचारिक documentation चाहिए, यानी ऐसा documentation जिसमें सभी parameter configurations हों। उदाहरण के लिए, requests docs में Google अक्सर मुझे Quickstart जैसे examples से भरे पेज पर भेज देता है, जो परेशान करता है। HTTP GET तो सब जानते हैं, लेकिन बाकी options क्या हैं, timeout कैसे handle होता है, या raise_for_status 204 को ignore करता है या नहीं—यह ढूँढ़ना मुश्किल है। दोनों चीज़ें चाहिए, लेकिन अगर developer time कम हो तो मैं पहले सही documentation देने को चुनूँगा। requests Quickstart example link

    • examples देखकर behavior को reference-स्टाइल docs की तुलना में कहीं ज़्यादा आसानी से समझा जा सकता है। लोग naming, concept organization, और documentation writing—तीनों में कमज़ोर होते हैं। हाल में भी मैं एक ऐसे parameter पर घंटों फँसा रहा जो सिर्फ कुछ conditions में काम करता था। code समझना बहुत जटिल था, और LLM ने भी ग़लती से कह दिया कि यह undocumented parameter है। आख़िरकार example code बनाकर इच्छित behavior ढूँढ़ना सबसे असरदार तरीका निकला। examples कई महत्वपूर्ण बातों को संक्षेप में समेटकर जल्दी verify करने देते हैं। इसके उलट API docs हर चीज़ को कवर करने की कोशिश में maintain करना मुश्किल बना देते हैं और core point भी साफ़ नहीं कर पाते। और जब तक कोई चीज़ स्पष्ट न हो, मैं लाइब्रेरी के behavior पर कभी भरोसा नहीं करता। अगर README में behavior साफ़ न दिखे या types में defined न हो, तो मैं मानकर चलता हूँ कि वह कभी भी बदल सकता है। इसलिए मैं calling code को जितना हो सके उतना defensive लिखता हूँ

    • examples सिर्फ beginners नहीं, सबके लिए अहम हैं। 5 सेकंड का example एक घंटे के docs पढ़ने और प्रयोग करने जितनी efficiency दे सकता है। git के कुछ docs ऐसे ही हैं, और मूल रूप से सरल लेकिन समझाने में कठिन functions पर भी यही लागू होता है। अगर developer सिर्फ एक चीज़ बना सकता हो, तब भी उसके पास examples और documentation दोनों देने लायक सामर्थ्य होनी चाहिए। दोनों देने चाहिए; अपवाद सिर्फ वही मामले हों जहाँ बात बिल्कुल स्वयंस्पष्ट हो

    • सहमत। अच्छा documentation लगभग पूरे program behavior को स्पष्ट रूप से define कर देना चाहिए, और सिर्फ examples से यह काम करना मुश्किल है

    • दोनों साथ हो सकते हैं। examples और technical documentation परस्पर विरोधी नहीं हैं

    • occasional users की बात ही तो मैं कर रहा हूँ। project, language, framework के बीच आते-जाते हर बार context वापस पाना और समझना कि स्थिति क्या है, यह काफ़ी mental cost लेता है

  • कुछ लोग Perl के बारे में चाहे जो कहें, Perl documentation सच में मददगार है। उसमें हमेशा शुरुआत में SYNOPSIS section होता है, जहाँ तुरंत इस्तेमाल करने लायक example code मिलता है। उसके बाद explanation, reference, और अतिरिक्त examples आते हैं। उदाहरण: bigrat docs, Archive::Tar docs. project documentation लिखते समय Perl style को देखना चाहिए। और वह style खुद भी अच्छी तरह व्यवस्थित है

    • मैंने 2000 के शुरुआती दशक में Perl इस्तेमाल किया था, फिर 2014 में संयोग से दोबारा करना पड़ा, और ऐसा लगा जैसे सब फिर से याद आने लगा हो। शायद Larry Wall के linguistic नज़रिए और रवैये की वजह से, यह बहुत गहरी छाप छोड़ता है। यह गणितीय precision की वजह से नहीं, बल्कि किसी "दोस्त से बात करने" जैसा एहसास देता है

  • दोनों चाहिए। examples देखकर तुरंत अंदाज़ा मिलता है, integration आसान होता है, और detailed parameters व config values की explanation tool की जटिल समस्याएँ सुलझाने और पूरी समझ बनाने में मदद करती है। इनमें से एक भी चीज़ गायब हो तो सचमुच दिक्कत होती है। हाँ, बहुत simple libraries में examples ही सब कुछ समझा सकते हैं

    • examples और reference docs दोनों चाहिए। संभव हो तो REPL environment भी जोड़ना अच्छा रहेगा। अगर examples को वहीं बदलकर test किया जा सके, तो documentation की कमी की कई कमियाँ काफ़ी हद तक पूरी हो जाती हैं

  • Diátaxis framework अच्छी तरह दिखाता है कि documentation कई प्रकार की होती है और हर एक का अपना उद्देश्य होता है। कौन-सा "सबसे अच्छा" है, यह सवाल नहीं; अलग-अलग ज़रूरतों के लिए अलग प्रकार ज़रूरी हैं। Diátaxis आधिकारिक साइट

    • यह बात इतनी महत्वपूर्ण है कि इसे सबसे ऊपर होना चाहिए था। इतनी लंबी बहस के बाद जाकर Diátaxis का ज़िक्र आना थोड़ा खीझ दिलाने वाला है। मेरी नज़र में examples documentation का मुख्य हिस्सा ज़रूर हैं, लेकिन अपने-आप में कोई स्वतंत्र "documentation type" कम और एक महत्वपूर्ण "documentation technique" ज़्यादा हैं

    • सही! examples (या tutorials) system education का एक पहलू हैं। यह किसने पहले बनाया, पक्का नहीं, लेकिन लिंक लेख के अंत में दिए गए लेखक के लिंक जैसा ही लगता है: > "बड़े projects में भी चारों तरह की documentation एक साथ मिलना दुर्लभ है। इसी वजह से कई बार ‘Documentation’ लिंक पर क्लिक करने में हिचक होती है" मुझे explanatory docs पसंद हैं। अगर structure और behavior के पीछे का कारण समझ में आ जाए, तो examples और tutorials भी आसानी से आत्मसात हो जाते हैं। जब कोई कुशल technical writer या educator शुरू से यह ढाँचा ठीक से बना दे, तो उसका असर बहुत बड़ा होता है। दूसरी तरफ़ API reference सबसे ज़्यादा तब चाहिए होता है जब wrappers या compatible implementations लिखनी हों। मूल रूप से कई projects private API reference से शुरू हुए थे, और documentation का काम बस उसे बाहर उपलब्ध कराना था। divio documentation system देखें

    • Diátaxis का विचार शानदार है। लेकिन इसे वास्तविक projects में लागू करना आसान नहीं है। हर project में documentation के प्रकारों का अनुपात अलग होता है, और सभी रूपों को एक ही website में रखना हमेशा असरदार नहीं होता। community की growth और expertise के साथ यह अनुपात लगातार बदलता भी रहता है। काश कोई और व्यावहारिक तरीका होता। documentation कठिन काम है, और उम्मीद है कि कभी न कभी इससे बेहतर हल मिलेगा। फिलहाल तो इसकी quality समय और expertise के निवेश पर निर्भर करती है, और आम तौर पर वही कम पड़ता है

  • Unity और Unreal में मुझे यह समस्या बहुत बार महसूस होती है। खासकर Unreal के node docs में अक्सर सिर्फ node का screenshot और उसका नाम दोहरा दिया जाता है, लेकिन असल में उसे कैसे इस्तेमाल करना है यह बिल्कुल नहीं बताया जाता। Unity में भी कई बार किसी function का सही उपयोग जानने के लिए docs खोजता हूँ, और वहाँ कुछ होता ही नहीं। मौका मिले तो मैं खुद Unity docs में examples contribute करना चाहूँगा

    • Unreal की खराब documentation मेरे लिए भी बहुत बड़ा time sink है। वहाँ "code ही documentation है" जैसी मानसिकता दिखती है, लेकिन Blueprint के लिए जो "node screenshot explanation" है, वह सचमुच हँसी लायक स्तर का है

    • £JOB को लेकर, जब लोग $job लिखते हैं तो क्या उनका मतलब पैसे कमाने वाली नौकरी/task से होता है, या यह बस variable name से आया है? इस बिंदु पर मेरी दुनिया की समझ ही हिल रही है

  • मैं ImageMagick अक्सर इस्तेमाल करता हूँ, और हमेशा examples ढूँढ़ने के लिए Google करना पड़ता था। इसलिए मैंने अपने निजी notes को छोटे command examples के संग्रह में समेट दिया। हर argument की detailed explanation भी जोड़ी। इस ब्लॉग पोस्ट की तरह सिर्फ examples नहीं, explanations भी साथ होनी चाहिए—मैं ऐसा मानता हूँ। अभी यह draft चरण में है, लेकिन resize, optimization, layering जैसे रोज़मर्रा के कामों में पहले से ही बहुत उपयोगी है। मेरे notes का सार्वजनिक लिंक

  • code examples को unit tests की तरह चलाकर documentation के पुराना पड़ने या टूटने से बचाया जा सकता है। प्राकृतिक भाषा में यह फायदा संभव नहीं है

    • अब LLM के आगे बढ़ने के साथ, उदाहरण के लिए API docs की accuracy verify करने की कोशिश भी की जा सकती है

  • एक उग्र राय: अगर किसी specific method का spec सिर्फ signature और कुछ representative examples देखकर सहज रूप से समझ में नहीं आता, तो वह method शायद बहुत ज़्यादा काम करने की कोशिश कर रहा है। मैं ऐसी abstraction नहीं सीखना चाहता जो रास्ता रोके, न ही बेवजह के जटिल exceptions

    • मैं इससे सहमत नहीं हूँ। examples सिर्फ उस method को नहीं, बल्कि यह भी दिखाने के लिए ज़रूरी हैं कि उसे "दूसरे methods के साथ कैसे इस्तेमाल किया जाए"। भले ही method signature देखकर सब अनुमान लगाया जा सके, फिर भी setup की कमी, तैयारी की प्रक्रिया, या result handling जैसी महत्वपूर्ण बातें छूट सकती हैं। इसलिए examples अनिवार्य हैं
 
howudoin 2025-10-11

Java ecosystem और object-oriented संस्कृति में खास तौर पर बेकार व्याख्यात्मक वाक्य और औपचारिक documentation बहुत रही है, और उसी माहौल को अपनाने वाले Python ecosystem के frameworks में भी उदाहरण खास तौर पर कमजोर होते हैं.

बेमतलब documentation का एक उदाहरण
add(left, right) - बाएँ operand और दाएँ operand को जोड़ता है

जबकि वास्तव में महत्वपूर्ण चीज़ें जैसे parameter का data type, कौन-कौन से exception return हो सकते हैं, result value का रूप, या operation की संरचना जैसी बातें समझाई ही नहीं जातीं.

अगर C language के man page जैसा हो, तो सिर्फ छोटी-सी व्याख्या के साथ भी function और parameter names से अंदाज़ा लगाकर इस्तेमाल किया जा सकता है.