इस पेज में, Docs के Google सीज़न के लिए स्वीकार किए गए तकनीकी राइटिंग प्रोजेक्ट की जानकारी दी गई है.
प्रोजेक्ट की खास जानकारी
- ओपन सोर्स संगठन:
- क्रिएटिव कॉमंस
- तकनीकी लेखक:
- निमिशन
- प्रोजेक्ट का नाम:
- शब्दावली के इस्तेमाल से जुड़ी गाइड
- प्रोजेक्ट की अवधि:
- मानक अवधि (तीन महीने)
प्रोजेक्ट का विवरण
प्रोजेक्ट की खास जानकारी
वेबसाइट बनाने के लिए, यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट की मुख्य लाइब्रेरी के तौर पर, शब्दावली को काफ़ी बेहतर बनाया जा सकता है. इसकी ज़रूरत है, लेकिन आसान और आम लोगों के लिए सही 'कैसे करें' गाइड. डेवलपर के बारे में अहम जानकारी, जैसे कि कॉम्पोनेंट गाइड, इस्तेमाल से जुड़ी खास बातें, और कॉन्फ़िगरेशन में बदलाव करना, किसी भी दस्तावेज़ का एक अहम हिस्सा होती है. इससे मौजूदा उपयोगकर्ताओं को न सिर्फ़ यह समझने में मदद मिलेगी कि शब्दावली कैसे बढ़ रही है और किस तरह नई उपलब्धियां हासिल की जा रही हैं. साथ ही, इससे नए प्रोजेक्ट की तुलना में शब्दावली के इस्तेमाल को भी बढ़ावा मिलेगा. एक इंटर्न के रूप में मुझे जो काम करना है उसका नतीजा सिर्फ़ पहले से मौजूद कॉम्पोनेंट इस्तेमाल करने के लिए बिना किसी तड़क-भड़क वाली गाइड तैयार करने के साथ-साथ शब्दावली, Vue-Vocabulary, और फ़ॉन्ट के लिए एक होम पेज को डिज़ाइन करने और बनाने के बारे में है. इसमें हर एक के लिए इंटिग्रेट किए गए दस्तावेज़ शामिल हैं.
प्रोजेक्ट प्लान
समस्या: दस्तावेज़ की मदद से यह तय होता है कि कोई ओपन सोर्स लाइब्रेरी कितनी कामयाब होगी. अपने ऐप्लिकेशन बनाने के लिए कोई सही टेक्नोलॉजी स्टैक चुनते समय, डेवलपर के मन में एक बड़ा सवाल यह होता है कि “क्या लाइब्रेरी को सही तरह से पेश किया गया है? क्या इसका रखरखाव ठीक से किया जा रहा है? क्या इसका कुछ अच्छा इस्तेमाल और गड़बड़ी के लिए मदद मिली है?”. इस प्रोजेक्ट के आइडिया के बारे में बात करते समय, हमें खुद से ये सवाल पूछने चाहिए. सॉफ़्टवेयर इंजीनियरिंग के नज़रिए से:
ज़रूरत का विश्लेषण: हमें अपनी ज़रूरतों के हिसाब से कम शब्दों और सभी ज़रूरी दस्तावेज़ों की ज़रूरत होती है. दस्तावेज़ों की कमी से ओपन सोर्स ऐप्लिकेशन के भविष्य के नज़रिए को नुकसान पहुंचता है और अब तक यह एक ज़रूरी और ग़ैर-ज़रूरी कॉम्पोनेंट है. इन दस्तावेज़ों का लिंक एक आकर्षक होम पेज होना चाहिए, जो लोगों का तुरंत हित कैप्चर करता हो. दस्तावेज़ सही तरीके से व्यवस्थित होना चाहिए, ताकि वह बिना किसी रुकावट के प्रोसेस हो सके.
खास जानकारी: ज़रूरी शर्तों के आधार पर, यह तय किया जा सकता है कि कौनसी जानकारी दी जाए. दस्तावेज़ों में दिया गया कॉन्टेंट, सीसी नेटलिफ़ाई वेबसाइटों में मौजूद डेटा के साथ-साथ सिमैंटिक-यूई, scikit-learn, numpy, बूटस्ट्रैप वगैरह से मिले डेटा से लिया जा सकता है. इस टास्क का आउटपुट, ज़रूरी लैंडिंग पेज और दस्तावेज़ों की पूरी गाइड होगा.
फ़िलहाल, शब्दावली, Vue-Vocabulary, और फ़ॉन्ट से जुड़ी कुछ सामान्य समस्याएं:
इसके लिए, उन्हें ज़रूरी दस्तावेज़ नहीं दिए जाएंगे. इतना ही नहीं, इन दस्तावेज़ों के कुछ हिस्से, नेटलाइज़ की गई वेबसाइटों पर बिखरे हुए हैं. इससे उपयोगकर्ता, डेवलपर या बाहरी योगदान देने वाले लोग हमारी लाइब्रेरी का इस्तेमाल नहीं कर पाएंगे.
किसी खास कॉम्पोनेंट पर जाने और उससे जुड़े कोड को कॉपी करने के लिए, कुछ और क्लिक करने होते हैं. “टैब कंपोनेंट सीसी शब्दावली” जैसी कोई सामान्य Google खोज, मनचाही जानकारी नहीं देती है. दस्तावेज़ों की गाइड में खोज के विकल्प देने से, उपयोगकर्ता अनुभव को काफ़ी बेहतर बनाया जा सकता है.
कॉम्पोनेंट के बारे में कम शब्दों में ज़्यादा जानकारी, जो साफ़ तौर पर नहीं पता चलती है.
लाइव चलाने का कोई विकल्प नहीं है. लाइव रन, JSFiddle जैसी कई साइटों के साथ काम करते हैं. इससे, डेवलपर को कॉम्पोनेंट के बारे में जानने की सुविधा मिलती है. इसके लिए, किसी ऐप्लिकेशन को पूरा इस्तेमाल नहीं करना पड़ता, ताकि वह काम करता रहे.
समाधान
इसके कई समाधान हो सकते हैं. हालांकि, मैं यहां उनमें से कुछ की बात करूंगा और निष्कर्ष में दिए गए अपने आखिरी समाधान के बारे में बताऊं:-
= Readthedocs का इस्तेमाल करना ओपन सोर्स लाइब्रेरी के लिए दस्तावेज़ लिखने का एक जाना-पहचाना समाधान है. यह स्फ़िंक्स पर आधारित है, जो कि Python दस्तावेज़ टूल है.
फ़ायदे:
- दस्तावेज़ जनरेट करने का ऐसा तरीका जो बड़े पैमाने पर स्वीकार किया जाता है. इसका इस्तेमाल, Ethereum (Solidity) जैसे संगठन करते हैं.
- बेहतर तरीके से स्ट्रक्चर किया गया दस्तावेज़.
- मुफ़्त स्टैटिक होस्टिंग.
नुकसान:
- स्टाइल पर पूरा कंट्रोल नहीं होता.
= Sprint का इस्तेमाल करना हम मूल रूप से दस्तावेज़ के हिस्से के लिए स्फ़िंक्स का इस्तेमाल कर सकते हैं, यह हमारे सभी कामों के लिए अच्छी सुविधाएं देता है.
फ़ायदे:
- दस्तावेज़ों के लिए, सबसे लोकप्रिय Python टूल.
- दस्तावेज़ खोजने की सुविधा भी उपलब्ध है.
- डिफ़ॉल्ट सीएसएस को पसंद के मुताबिक बनाया गया सीएसएस बदला जा सकता है. साथ ही, .rst फ़ाइलों का इस्तेमाल करके, एचटीएमएल पर कुछ कंट्रोल किया जा सकता है.
नुकसान:
- इसमें Python में कोडिंग और फिर से बनाए गए टेक्स्ट फ़ॉर्मैट (.rst) का इस्तेमाल किया जाएगा. यह सुझाए गए प्रोजेक्ट की भाषाओं से अलग होगा.
= Jekyll थीम का इस्तेमाल करना Jekyll की थीम को GitHub पेजों में इंटिग्रेट किया गया है और पहले से मौजूद ऐसे टेंप्लेट मौजूद हैं जिन्हें हमारी ज़रूरतों के हिसाब से, पसंद के मुताबिक बनाया जा सकता है.
फ़ायदे:
- सभी मकसद के लिए, दस्तावेज़ की पहले से तैयार थीम.
- डिफ़ॉल्ट सीएसएस और स्टाइल, पसंद के मुताबिक बनाए गए सीएसएस और स्टाइल से बदल सकते हैं. साथ ही, इन्हें एचटीएमएल पर भी कंट्रोल किया जा सकता है.
- पेज बनाने के लिए डिफ़ॉल्ट प्राइमर सीएसएस को पुल करता है.
- GitHub पेजों के साथ आसान इंटिग्रेशन.
नुकसान:
- ऐसा हो सकता है कि यह दस्तावेज़ बनाने का सबसे अच्छा तरीका न दे.
=GitHub पेजों का इस्तेमाल करना हमारी स्टैटिक साइट (एचटीएमएल, सीएसएस, JS) बनाने के लिए स्टैंडर्ड GitHub पेज.
फ़ायदे:
- करीब-करीब उन सभी चीज़ों पर पूरा कंट्रोल: जिन पर कार्रवाई की जा रही है.
- लेआउट, रंग, और स्टाइल तय करने के लिए ज़्यादा से ज़्यादा सुविधा.
- शब्दावली के कॉम्पोनेंट आसानी से इस्तेमाल किए जा सकते हैं.
- इसमें कोड स्निपेट और लाइव रन लिंक को आसानी से एम्बेड किया जा सकता है.
नुकसान:
- यह तरीका ज़्यादा समय लेने वाला हो सकता है.
= Haroopad का इस्तेमाल करने पर इससे मार्कडाउन का विकल्प मिल जाता है.
फ़ायदे:
- इसके लिए, फ़िज़िकल कोडिंग की ज़रूरत नहीं होगी.
- हमारा फ़ोकस दस्तावेज़ को सही तरीके से लिखने पर रहेगा.
नुकसान:
- सीएसएस पर कंट्रोल नहीं है.
- ऐसा भी हो सकता है कि आपको कम्यूनिटी की बेहतरीन मदद मिले या नहीं.
- ऐसा हो सकता है कि यह एमडीएक्स के साथ काम न करे.
= MKDocs का इस्तेमाल करने पर यह मार्कडाउन के बजाय एक अन्य विकल्प देता है.
फ़ायदे:
- कम से कम फ़िज़िकल कोडिंग (फिर से) शामिल होगी.
- ज़्यादा लिखें और कोड कम तरीका अपनाएं.
नुकसान:
- सीएसएस पर कंट्रोल नहीं है.
- ऐसा हो सकता है कि आपको कम्यूनिटी से बेहतरीन मदद न मिले.
- Python का इस्तेमाल किया जाता है. इसलिए, Amazon S3 के इंस्टेंस को स्पिथन का इस्तेमाल करने की ज़रूरत पड़ सकती है.
= VueJS +StorybookJS का इस्तेमाल करना यह तरीका, आम तौर पर शब्दावली और इसके अन्य डेटा स्टोर करने की जगहों में इस्तेमाल किया जाता है.
फ़ायदे:
- अपने काम के अनुभवों के आधार पर, ऐसी टेक्नोलॉजी का इस्तेमाल करना चाहिए जो अच्छी तरह से काम करेंगी.
- कोड बेस के बारे में जानकारी.
- इस क्षेत्र में कोई सक्षम तकनीक नहीं है.
नुकसान:
- उसी मकसद के लिए, आसान विकल्प भी मौजूद हो सकते हैं.
आखिर में, मेरे हिसाब से VueJS+Storybook अप्रोच (HTML,CSS,JS) वाला तरीका सबसे सही लग रहा है, क्योंकि यह मेरे लिए भी सही है. हालांकि, इसका मतलब यह भी है कि हम इस ऐप्लिकेशन को डेवलप करने के अपने तरीके से कुछ भी नहीं कर पाएंगे. सीसी-शब्दों के कॉम्पोनेंट का इस्तेमाल करना भी काफ़ी आसान होगा. हालांकि, दस्तावेज़ का स्ट्रक्चर तय करने से पहले, हमें इस बात पर ध्यान देना होगा कि कॉन्टेंट को, Readthedocs के दस्तावेज़ों में उप-खातों के बीच बांटा गया है या नहीं. मैं सिमैंटिक-यूज़र इंटरफ़ेस (यूआई) वेबसाइट (जिसमें StoryBook का इस्तेमाल किया जाता है) से बहुत प्रभावित हुए हैं, क्योंकि इसका लुक बहुत छोटा है. साथ ही, कोई भी व्यक्ति कुछ ही क्लिक में आसानी से जान सकता है कि उसे क्या चाहिए. सिमैंटिक-यूआई के अलावा, मैंने मटीरियल डिज़ाइन, प्राइमर, बूटस्ट्रैप, कार्बन डिज़ाइन वगैरह के बारे में भी जाना. इसे मेरे काम के लिए यूज़र इंटरफ़ेस (यूआई) स्टाइल गाइड और डिज़ाइन सिस्टम के तौर पर इस्तेमाल किया जा सकता है. इसके लिए, हम पहले से तैयार Jekyll की दस्तावेज़ थीम भी देख सकते हैं.