- esbuild और Redis ऐसे codebase के उदाहरण हैं जिनकी documentation बेहतरीन है।
- README, changelog, architecture document और code comments के ज़रिए नए उपयोगकर्ता भी codebase की संरचना, उसके काम करने के तरीके और उसके पीछे के कारणों को समझ सकते हैं।
- यह उन developers के लिए अच्छे case study हैं जो code और software architecture documentation को बेहतर बनाना चाहते हैं।
अच्छी documentation क्यों महत्वपूर्ण है
- software लिखते समय, खासकर जब कोई दूसरा व्यक्ति codebase को देखे या उसमें योगदान दे, या बाद में आप स्वयं उसे फिर से देखें, तब अच्छी documentation आवश्यक होती है।
- software उपयोगकर्ताओं को अक्सर documentation की कमी के कारण कठिनाइयों का सामना करना पड़ता है।
- यदि आप किसी codebase में योगदान कर रहे हैं, तो documentation की गुणवत्ता जितनी अच्छी होगी, आप उतनी तेज़ी से योगदान कर पाएँगे।
- documentation की गुणवत्ता लेखक, contributor या उपयोगकर्ता के अनुभव को सीधे या परोक्ष रूप से प्रभावित करती है।
- अच्छी documentation के कई लाभ हैं: समय की बचत, open source प्रोजेक्ट्स में बाहरी योगदान में वृद्धि, पुराने निर्णयों का रिकॉर्ड, अधिक उपयोगकर्ताओं के लिए पहुँच, सोच को व्यवस्थित करना और समस्याओं की पहचान करना।
esbuild की documentation
- esbuild, Evan Wallace द्वारा बनाया गया JavaScript bundler है।
- esbuild का README टूल के अंतिम उपयोगकर्ताओं पर केंद्रित है।
- दस्तावेज़ के मुख्य sections के links और "क्यों?" सेक्शन के माध्यम से संक्षेप में समझाया गया है कि दूसरे bundlers की तुलना में esbuild क्यों चुनना चाहिए।
- esbuild के architecture documents
docs directory में architecture.md और development.md फ़ाइलों के रूप में मौजूद हैं।
- architecture document design principles समझाता है और इसमें केवल text ही नहीं, बल्कि concepts समझाने वाले graphics भी शामिल हैं।
- esbuild का changelog विस्तृत है, जिसमें summary, विस्तारित विवरण और बदलाव से पहले/बाद के example code शामिल हैं।
Redis की documentation
- Redis एक in-memory database है।
- Redis का README, esbuild के README जैसी अच्छी विशेषताएँ साझा करता है, लेकिन यह contributors और अंतिम उपयोगकर्ताओं दोनों पर केंद्रित है।
- Redis के internals पर section में source code layout और मुख्य files का विवरण शामिल है।
- Redis source code के भीतर code comments, code की एकल पंक्ति के लिए भी कई paragraphs में स्पष्टीकरण देते हैं।
समापन
- कई open source प्रोजेक्ट्स में बेहतरीन documentation होती है।
- esbuild और Redis विशेष रूप से अपनी उत्कृष्ट documentation के कारण प्रभावशाली हैं।
- documentation अल्पकाल में समय की बाधा पैदा कर सकती है, लेकिन दीर्घकाल में यह समय बचाती है।
- जिन प्रोजेक्ट्स का बहुत से लोग उपयोग करते हैं या उनमें योगदान देते हैं, उनमें documentation न करने के बारे में दोबारा सोचना चाहिए।
GN⁺ की राय
- esbuild और Redis की documentation के उदाहरण developers को यह बताते हैं कि documentation codebase को समझने और उसका रखरखाव आसान बनाने में कितनी महत्वपूर्ण है।
- documentation प्रोजेक्ट की स्थिरता बढ़ाने और community participation को प्रोत्साहित करने वाला एक प्रमुख तत्व है।
- esbuild के मामले में, तेज़ JavaScript bundler होने के साथ-साथ बेहतरीन documentation ने भी प्रोजेक्ट की वृद्धि में योगदान दिया है, ऐसा लगता है।
- Redis ने ऐसी documentation के कारण developer community पर सकारात्मक प्रभाव डाला है जो एक जटिल in-memory database system को आसानी से समझने में मदद करती है।
- ऐसे उदाहरण अन्य open source प्रोजेक्ट्स में भी documentation के महत्व को फैलाने में मदद कर सकते हैं, और खासकर शुरुआती software engineers के लिए अपने प्रोजेक्ट्स को document करने का तरीका समझने में उपयोगी हैं।
2 टिप्पणियां
esbuild में README.md फ़ाइल तो बढ़िया है ही, लेकिन लेख में परिचित कराया गया architecture.md फ़ाइल भी बेहद खूबसूरत है!
Hacker News राय
Redis के संस्थापक Antirez ने अपने ब्लॉग पर code comments के बारे में अपने विचारों को विस्तार से समझाते हुए एक लेख लिखा। उन्होंने Redis में इस्तेमाल होने वाले comments के 9 प्रकारों की पहचान की।
project documentation उपयोगकर्ताओं/developers/contributors के लिए किस तरह शानदार हो सकती है, इस पर ठोस उदाहरणों और screenshots के साथ लिखा गया एक अच्छा लेख।
यह maintainers की repository की quality के प्रति चिंता को दिखाता है।
इससे "The Architecture of Open Source Applications" series की याद आती है। इसमें दिलचस्प insights हैं।
GitLab की documentation बहुत अच्छी मानी जाती है, लेकिन उसे सीधे इस्तेमाल करने की ज़रूरत ज़्यादा नहीं पड़ी। उनकी architecture documentation भी अच्छी है या नहीं, यह सवाल है।
Postgres project भी documentation, readme files, और code comments पर बारीकी से ध्यान देता है।
esbuild project की architecture documentation से बहुत गहरा प्रभाव पड़ा। काश पहले जिन codebases पर काम किया था, उनमें भी ऐसी documentation होती।
open source projects के changelogs बहुत पसंद हैं। वे मुनाफ़ा कमाने वाली दूसरी entities की तुलना में कहीं अधिक professional और informative होते हैं। ING बैंक के app changelog की आलोचना की गई कि उसे मज़ाकिया होने के बजाय जानकारी देने पर ध्यान देना चाहिए।
"आज की free software community में सबसे बड़ी कमी software की नहीं, बल्कि उस अच्छे free documentation की है जिसे free software के साथ शामिल किया जा सके।"
यह भी उल्लेख किया गया कि Redis अब open source नहीं है। Redis, Redis Source Available License v2 (RSALv2) और Server Side Public License v1 (SSPLv1) के तहत "source-available" software है।