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