इस पेज पर, Google Season of Docs के लिए स्वीकार किए गए टेक्निकल राइटिंग प्रोजेक्ट की जानकारी दी गई है.
प्रोजेक्ट समरी
- ओपन सोर्स संगठन:
- AboutCode
- टेक्निकल राइटर:
- ayansinha
- प्रोजेक्ट का नाम:
- scancode-toolkit में कमांड लाइन के विकल्पों के लिए रेफ़रंस और aboutcode.readthedocs.io पर AboutCode के दस्तावेज़ के स्ट्रक्चर को फिर से व्यवस्थित करना
- प्रोजेक्ट की अवधि:
- स्टैंडर्ड अवधि (तीन महीने)
प्रोजेक्ट का विवरण
[ 1. Scancode-Toolkit के कमांड लाइन के विकल्प ]
Scancode-Toolkit में कमांड लाइन के कई विकल्प मौजूद हैं. इनकी मदद से, स्कैन करने का तरीका, आउटपुट का फ़ॉर्मैट, और स्कैन के बाद इस्तेमाल किए जाने वाले प्लगिन जैसे कई अन्य विकल्पों को पसंद के मुताबिक बनाया जा सकता है. फ़िलहाल, इन विकल्पों के बारे में बताने के लिए कोई दस्तावेज़ मौजूद नहीं है. ये विकल्प सिर्फ़ “--help” या “-h” फ़्लैग के ज़रिए उपलब्ध हैं. इस प्रोजेक्ट का मकसद, एक ऐसा पूरा दस्तावेज़ बनाना है जिसमें इन विषयों के बारे में बताया गया हो:
[ 1. कमांड लाइन के ज़रिए उपलब्ध सभी विकल्प ]
- लक्ष्य: कमांड लाइन के ज़रिए उपलब्ध सभी विकल्पों की पूरी सूची.
- खास जानकारी: सबसे पहले, डिफ़ॉल्ट स्कैन विकल्पों के बारे में बताया जाता है. इसके साथ ही, आउटपुट का एक उदाहरण भी दिया जाता है. स्कैन करने के तरीके के बारे में एक छोटा ग्राफ़िक/ब्यौरा.
इसके बाद, डिफ़ॉल्ट व्यवहार को रेफ़रंस के तौर पर इस्तेमाल किया जाता है. इससे यह पता चलता है कि अन्य विकल्पों की मदद से, स्कैन करने के तरीके और आउटपुट में कैसे बदलाव किया जा सकता है.
इनके बारे में विस्तार से बताया जाएगा. साथ ही, इनमें अगली सेक्शन में बताई गई जानकारी शामिल होगी.
[ 2. वर्शनिंग स्ट्रक्चर शुरू करना ]
- लक्ष्य: वर्शनिंग सिस्टम शुरू करना, ताकि अलग-अलग रिलीज़ में उपलब्ध विकल्पों/एपीआई और दस्तावेज़ में किए गए बदलावों को सही तरीके से बनाए रखा जा सके.
- समस्या: फ़िलहाल, विकी और ReadTheDocs पेजों पर मौजूद दस्तावेज़, पुराने वर्शन के लिए हैं. इसलिए, इनमें बड़े बदलाव करने की ज़रूरत है.
- खास जानकारी: scancode-toolkit के वे हिस्से जिन्हें अपडेट किया गया है/जिनके वर्शन में अपडेट किया जा सकता है, वे ये हैं:
- कमांड लाइन के विकल्प
- एपीआई
- दस्तावेज़ (शुरू किया जाना है) वर्शन और रिलीज़ में, कमांड लाइन के विकल्पों और एपीआई में बदलाव किए जाते हैं. इसलिए, दस्तावेज़ में भी बदलाव करने होंगे. ऐसा न करने पर, उपयोगकर्ताओं को काफ़ी परेशानी हो सकती है. कमांड लाइन यूटिलिटी [ --help ] को विकल्पों में किए गए किसी भी बदलाव के लिए पहले ही अपडेट कर दिया गया है. इसका इस्तेमाल, दस्तावेज़ में वर्शनिंग को दोहराने के लिए किया जा सकता है.
[ 3. अलग-अलग मामलों में इन विकल्पों का इस्तेमाल कैसे किया जा सकता है ]
- लक्ष्य: इस सेक्शन में, scancode-toolkit के स्कैन के नतीजों का इस्तेमाल अलग-अलग वजहों से कैसे किया जा सकता है, इसके बारे में खास जानकारी दी जाएगी. साथ ही, इसमें Scancode-Toolkit के उन विकल्पों के बारे में भी बताया जाएगा जिनकी मदद से यह सुविधा मिलती है.
- खास जानकारी: इस सेक्शन में, इस्तेमाल के अलग-अलग उदाहरण दिए गए हैं. साथ ही, यह भी बताया गया है कि इन उदाहरणों में किन विकल्पों का इस्तेमाल करने का सुझाव दिया जाता है.
- ध्यान दें: इस हिस्से के लिए, मेंटर से काफ़ी मदद की ज़रूरत होगी. इसमें Scancode-Toolkit के अलग-अलग इस्तेमाल के उदाहरणों के बारे में जानकारी और पॉइंटर शामिल हैं.
[ 4. स्कैन और आउटपुट में इन विकल्पों से क्या बदलाव होता है ]
- लक्ष्य: इस सेक्शन में, scancode-toolkit के स्कैन के नतीजों का इस्तेमाल अलग-अलग वजहों से कैसे किया जा सकता है, इसके बारे में खास जानकारी दी जाएगी. साथ ही, इसमें Aboutcode के उन टूल के बारे में भी बताया जाएगा जिनकी मदद से यह सुविधा मिलती है.
- खास जानकारी: विकल्पों की मदद से, स्कैन करने के तरीके में बदलाव किया जा सकता है. पहले सेक्शन [ 1. में एक बुनियादी डिफ़ॉल्ट केस का उदाहरण दिया जाएगा. कमांड लाइन के ज़रिए उपलब्ध सभी विकल्प ] में, डिफ़ॉल्ट तौर पर स्कैन करने के तरीके का एक उदाहरण दिया जाएगा. इस सेक्शन में, यह तुलना की जाएगी कि सभी विकल्पों की मदद से, डिफ़ॉल्ट तौर पर स्कैन करने के तरीके में क्या-क्या बदलाव किए जा सकते हैं.
[ 5. आउटपुट के फ़ॉर्मैट और उनके उदाहरण ]
- लक्ष्य: इस सेक्शन में, scancode-toolkit के स्कैन के नतीजों का इस्तेमाल अलग-अलग वजहों से कैसे किया जा सकता है, इसके बारे में खास जानकारी दी जाएगी. साथ ही, इसमें Aboutcode के उन टूल के बारे में भी बताया जाएगा जिनकी मदद से यह सुविधा मिलती है.
- खास जानकारी: Scancode-Tool में, आउटपुट के अलग-अलग फ़ॉर्मैट तय करने के लिए फ़्लैग मौजूद हैं. स्कैन के नतीजे, इन्हीं फ़ॉर्मैट में जनरेट किए जाएंगे. ये फ़्लैग ये हैं -
इस हिस्से में - आउटपुट के फ़ॉर्मैट के बारे में विस्तार से बताया जाएगा
- आउटपुट के फ़ॉर्मैट के उदाहरण दिए जाएंगे
- आउटपुट के फ़ॉर्मैट और उसके इस्तेमाल से जुड़े अन्य लिंक दिए जाएंगे
- स्कैन के नतीजे, आउटपुट फ़ाइलों में कैसे सेव किए जाते हैं, इसके बारे में बताया जाएगा. इसमें, अलग-अलग फ़ॉर्मैट कैसे जनरेट किए जाते हैं, इसके बारे में भी बताया जाएगा. इसकी जानकारी [ 2. कोड स्कैन करने के बारे में चर्चा ] में दी जाएगी.
[ 6. Scancode के आउटपुट फ़ॉर्मैट का इस्तेमाल कारोबार के लिए कैसे किया जा सकता है ]
- लक्ष्य: GSoD के आइडिया की सूची में, Scancode के आउटपुट फ़ॉर्मैट को रेफ़रंस आइडिया के तौर पर बताया गया है. इस सेक्शन में, Scancode के आउटपुट फ़ॉर्मैट के इस्तेमाल के उदाहरणों के बारे में बताया जाएगा. इस सेक्शन में, उसी आइडिया को लागू किया गया है.
- ध्यान दें: इस हिस्से के लिए, मेंटर से काफ़ी मदद की ज़रूरत होगी. इसमें Scancode-Toolkit के अलग-अलग इस्तेमाल के उदाहरणों के बारे में जानकारी और पॉइंटर शामिल हैं.
[ 7. ज़्यादा विश्लेषण के लिए, AboutCode के अन्य प्रोजेक्ट इन आउटपुट का इस्तेमाल कैसे करते हैं ]
- लक्ष्य: इस सेक्शन में, scancode-toolkit के स्कैन के नतीजों का इस्तेमाल अलग-अलग वजहों से कैसे किया जा सकता है, इसके बारे में खास जानकारी दी जाएगी. साथ ही, इसमें Aboutcode के उन टूल के बारे में भी बताया जाएगा जिनकी मदद से यह सुविधा मिलती है.
- खास जानकारी:
- Scancode-Workbench इस हिस्से में, डेस्कटॉप ऐप्लिकेशन की मदद से नतीजों को विज़ुअलाइज़ करने के बारे में बताया गया है. साथ ही, इसमें scancode-workbench के दस्तावेज़ के पॉइंटर भी शामिल हैं, ताकि इस बारे में ज़्यादा मदद मिल सके. ज़रूरत पड़ने पर, scancode-workbench में ज़रूरी दस्तावेज़ जोड़े जाएंगे.
- Deltacode दो कोडबेस के बीच फ़ाइल-लेवल के अंतर का पता लगाने के लिए, Deltacode, scancode के नतीजों का इस्तेमाल कैसे करता है.
[ 2. AboutCode के दस्तावेज़ के स्ट्रक्चर को फिर से व्यवस्थित करना ]
इस हिस्से में, Aboutcode के दस्तावेज़ में कई बदलाव किए गए हैं
[ 1. वर्शनिंग सिस्टम ]
[ 1. Scancode-Toolkit के कमांड लाइन के विकल्प -> 2. वर्शनिंग स्ट्रक्चर शुरू करना] में, कमांड लाइन के विकल्पों की वर्शनिंग की समस्या के बारे में बताया गया है. दस्तावेज़ के अन्य हिस्सों के लिए भी वर्शनिंग ज़रूरी है. इनमें वर्शन के हिसाब से कमांड/जानकारी शामिल होती है. ऐसा न करने पर, उपयोगकर्ताओं को काफ़ी परेशानी हो सकती है.
[ 2. दस्तावेज़ के स्टैंडर्ड और टेस्ट सेट करना ]
दस्तावेज़ में, spinx-build (सभी पेजों को बनाता है और Sphinx सिंटैक्स की गड़बड़ियों की जांच करता है) और लिंक की जांच (दस्तावेज़ से अन्य वेबपेजों के सभी लिंक की जांच करता है) के लिए पहले से ही टेस्ट मौजूद हैं. साथ ही, इसमें Travis-CI के ज़रिए लगातार इंटिग्रेशन की सुविधा भी है. (इसे मैंने इस पुल अनुरोध #17 में जोड़ा है) अब इसमें, reStructured Text और अन्य स्टैंडर्ड में खास लिंटिंग के लिए ज़्यादा जांच की ज़रूरत है. इसे restructuredtext-lint की मदद से किया जा सकता है. हालांकि, इसके लिए ज़्यादा रिसर्च की ज़रूरत है. इसे मेरे GSoD प्रोजेक्ट के हिस्से के तौर पर किया जाएगा.
[ 3. “शुरू करना” सेक्शन जोड़ना ]
यह सेक्शन, नए उपयोगकर्ताओं के लिए शुरुआती सेक्शन के तौर पर काम करेगा. इसमें Aboutcode के प्रोजेक्ट शुरू करने के लिए, सबसे बुनियादी और अहम दस्तावेज़ों का कलेक्शन शामिल होगा. Scancode-Toolkit, Scancode-Workbench, Deltacode वगैरह, Aboutcode के हर प्रोजेक्ट में यह सेक्शन शामिल होगा.
[ 4. दस्तावेज़ के चार फ़ंक्शन के हिसाब से स्ट्रक्चर को फिर से व्यवस्थित करना ]
मौजूदा दस्तावेज़, ट्यूटोरियल, तरीका बताने वाले लेख, रेफ़रंस, और जानकारी देने वाले लेख के तौर पर, दस्तावेज़ के चार फ़ंक्शन के हिसाब से व्यवस्थित नहीं है. मेरा सुझाव है कि इन्हें ज़रूरत के हिसाब से व्यवस्थित किया जाए. साथ ही, इनमें ज़्यादा जानकारी/उदाहरण/पॉइंटर जोड़े जाएं. यह AboutCode के सभी प्रोजेक्ट और उनके दस्तावेज़ों पर लागू होता है. यहां Scancode-Toolkit के दस्तावेज़ के स्ट्रक्चर को फिर से व्यवस्थित करने के दो उदाहरण दिए गए हैं. मेरा सुझाव है कि इस प्रोजेक्ट में इन्हें लागू किया जाए. दस्तावेज़ के बाकी हिस्सों में भी इसी तरह के बदलाव किए जाएंगे.
[ 5. डेवलपमेंट पेज (Scancode-Toolkit) के स्ट्रक्चर को फिर से व्यवस्थित करना ]
कोड/एपीआई के बारे में ज़्यादा जानकारी जोड़ी जा सकती है, ताकि यह डेवलपर के लिए ज़्यादा काम का हो. ऊपर दिए गए [ 2. कोड स्कैन करने के बारे में चर्चा ] सेक्शन के लिंक जोड़े जा सकते हैं. इससे, स्कैन करने के तरीके के बारे में दी गई जानकारी को उस कोड से लिंक किया जा सकता है जिसका इस्तेमाल स्कैन करने के लिए किया जाता है. इन फ़ोल्डर में scancode-toolkit के अलग-अलग हिस्से शामिल हैं. इनके अलग-अलग इस्तेमाल के बारे में, एपीआई की मदद से विस्तार से बताया जा सकता है. इसके साथ ही, scancode के काम करने के तरीके के बारे में भी बताया जा सकता है.
- [ cluecode : लाइसेंस, कॉपीराइट, यूआरएल, ईमेल स्कैन करने के लिए प्लगिन ]
- [ commoncode : हेल्पर क्लास और फ़ंक्शन]
- [ extractcode : अलग-अलग आर्काइव फ़ॉर्मैट एक्सट्रैक्ट करता है ]
- [ formattedcode : आउटपुट फ़ाइल के अलग-अलग फ़ॉर्मैट के लिए आउटपुट की फ़ॉर्मैटिंग ]
- [ licensedcode : लाइसेंस का पता लगाने वाला कोड ]
- [ packagedcode : पैकेज के अलग-अलग फ़ॉर्मैट को पार्स करना ]
- [ plugincode : प्लगिन आर्किटेक्चर के लिए क्लास ]
- [ summarycode : पता लगाए गए लाइसेंस के बारे में स्कैन की खास जानकारी देता है ]
- [ textcode : टेक्स्ट पार्सिंग को मैनेज करता है ]
- [ typecode : फ़ाइल टाइप की जानकारी को मैनेज करता है ]
- [ scancode : scancode के लिए सीएलआई और एपीआई, मुख्य हिस्सा ]
इस सबसेक्शन में, scancode-toolkit के इन हिस्सों के बारे में पूरी जानकारी/एपीआई शामिल होंगे. इन्हें सब-सबसेक्शन में व्यवस्थित किया जाएगा. डेवलपमेंट के दिशा-निर्देश, किसी दूसरे पेज या छोटे-छोटे सबसेक्शन वाले किसी दूसरे सेक्शन में मौजूद होंगे.
[ 6. अक्सर पूछे जाने वाले सवाल (एफ़एक्यू) वाले पेज (Scancode-Toolkit) के स्ट्रक्चर को फिर से व्यवस्थित करना ]
फ़िलहाल, एफ़एक्यू वाले पेज पर ऐसे सवाल हैं जिनके बेहतर जवाब दिए जा सकते हैं. साथ ही, इन्हें अलग-अलग तरीके से, तरीका बताने वाले लेख, ट्यूटोरियल, और रेफ़रंस दस्तावेज़ के तौर पर व्यवस्थित किया जाना चाहिए.
- ScanCode कैसे काम करता है? इस समस्या के बारे में [ 2. कोड स्कैन करने के बारे में चर्चा ] में बताया गया है. साथ ही, इसके बारे में ज़्यादा जानकारी देने के लिए, एक अलग सेक्शन बनाया जाएगा.
- बेहतर तरीके से लाइसेंस का पता लगाने के लिए, लाइसेंस के नए नियम कैसे जोड़ें? इस समस्या के बारे में, मौजूदा तरीका बताने वाले लेखों को बेहतर बनाने के दौरान पहले ही बताया जा चुका है. इसलिए, दस्तावेज़ को वहां ले जाया जाएगा.
- लाइसेंस का पता लगाने का नया नियम कैसे जोड़ें? इसे अलग से, “तरीका बताने वाला लेख” के तौर पर बनाया जा सकता है और इसके बारे में ज़्यादा जानकारी दी जा सकती है.
- डेवलपमेंट शुरू कैसे करें? डेवलपमेंट के लिए पहले से ही एक अलग पेज मौजूद है. साथ ही, दोनों में काफ़ी जानकारी एक जैसी है. डेवलपमेंट पेज के स्ट्रक्चर को फिर से व्यवस्थित करने के बारे में ऊपर बताया जा चुका है.
- नई रिलीज़ करने के चरण इसे “नई रिलीज़ कैसे करें” के तौर पर, एक अलग “तरीका बताने वाला लेख” बनाया जा सकता है.
- एफ़एक्यू के ऐसे और सवाल ढूंढें जिनके जवाब में प्रोजेक्ट के बारे में सामान्य जानकारी दी जाती है और जो “तरीका बताने वाले लेख”/”ट्यूटोरियल” कैटगरी में नहीं आते.