क्रिएटिव कॉमंस प्रोजेक्ट

इस पेज में एक तकनीकी लेखन प्रोजेक्ट की जानकारी है, जिसे दस्तावेज़ के Google सीज़न के लिए स्वीकार किया जाता है.

प्रोजेक्ट की खास जानकारी

ओपन सोर्स संगठन:

Creative Commons

टेक्निकल राइटर:

nimishnb

प्रोजेक्ट का नाम:

शब्दावली के इस्तेमाल से जुड़ी गाइड

प्रोजेक्ट की अवधि:

स्टैंडर्ड अवधि (तीन महीने)

प्रोजेक्ट का विवरण

प्रोजेक्ट की खास जानकारी

वेबसाइट बनाने के लिए, Vocabulary को मुख्य यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट लाइब्रेरी के तौर पर इस्तेमाल किया जा सकता है. इसके लिए एक मज़बूत, लेकिन आम लोगों के लिए आसान वीडियो बनाने की ज़रूरत है. डेवलपर से जुड़ी अहम जानकारी, जैसे कि कॉम्पोनेंट गाइड, इस्तेमाल की खास जानकारी, और कॉन्फ़िगरेशन में हुए बदलाव, किसी भी दस्तावेज़ का ज़रूरी हिस्सा बन जाते हैं. इससे न सिर्फ़ मौजूदा उपयोगकर्ताओं को लग पाएगा कि कैसे शब्दों का इस्तेमाल लगातार बढ़ रहा है और वे नई उपलब्धियां हासिल कर रहे हैं, बल्कि इससे दूसरे प्रोजेक्ट की तुलना में नए प्रोजेक्ट में शब्दावली के इस्तेमाल को भी बढ़ावा मिलेगा. इंटर्न के तौर पर मेरे काम के नतीजों में, पहले से मौजूद कॉम्पोनेंट का इस्तेमाल करने के लिए आसान गाइड तैयार करना शामिल है. साथ ही, Vocabulary, Vue-Vocabulary, और फ़ॉन्ट के लिए होम पेज डिज़ाइन और डेवलप करना भी शामिल है. इससे हर कॉम्पोनेंट के लिए एक इंटिग्रेटेड दस्तावेज़ तैयार होगा.

प्रोजेक्ट प्लान

1. समस्या: दस्तावेज़, ओपन सोर्स लाइब्रेरी की सफलता की मुख्य वजहों में से एक है. अपने ऐप्लिकेशन बनाने के लिए सही टेक स्टैक चुनते समय, डेवलपर यह सोचते हैं कि “क्या लाइब्रेरी के बारे में अच्छी तरह से जानकारी दी गई है? क्या इसका रखरखाव अच्छा है? क्या इसमें इस्तेमाल करने और गड़बड़ियों से जुड़ी कुछ अहम सुविधाएं हैं?”. प्रोजेक्ट के इस आइडिया के बारे में काम करते समय, हमें इन्हीं सवालों के जवाब खुद से रखने चाहिए. सॉफ़्टवेयर इंजीनियरिंग के हिसाब से:

2. ज़रूरी शर्तों का विश्लेषण: हमारी ज़रूरतों के हिसाब से, कम शब्दों में और सभी दस्तावेज़ों को एक साथ जोड़ना ज़रूरी है. दस्तावेज़ों की कमी, ओपन सोर्स ऐप्लिकेशन के भविष्य के नज़रिये पर बुरा असर डाल सकती है. साथ ही, अब तक यह एक ज़रूरी कॉम्पोनेंट है और उस पर ज़्यादा ध्यान नहीं दिया जाता है. इन दस्तावेज़ों का लिंक एक आकर्षक होम पेज होना चाहिए, जो लोगों का ध्यान तुरंत खींच सके. दस्तावेज़ों को अच्छी तरह से व्यवस्थित किया जाना चाहिए, ताकि उन्हें आसानी से पढ़ा जा सके.

3. खास जानकारी: ज़रूरतों के आधार पर, खास जानकारी तय की जा सकती है. दस्तावेज़ में मौजूद कॉन्टेंट, सीसी की netlify वेबसाइटों में मौजूद डेटा से बनाया जा सकता है. साथ ही, इसमें semantic-ui, scikit-learn, numpy, bootstrap वगैरह जैसे मशहूर दस्तावेज़ों से भी कुछ प्रेरणा ली जा सकती है. इस टास्क का आउटपुट, ज़रूरी लैंडिंग पेज और दस्तावेज़ की पूरी गाइड होगी.

फ़िलहाल, शब्दावली, Vue-शब्दावली और फ़ॉन्ट से जुड़ी कुछ सामान्य समस्याएं हैं:

• दस्तावेज़ मौजूद नहीं हैं. अगर कुछ दस्तावेज़ हैं, तो उनके हिस्से Netlify की वेबसाइटों पर अलग-अलग जगहों पर मौजूद हैं. इससे, उपयोगकर्ताओं, डेवलपर या बाहरी योगदान देने वालों को हमारी लाइब्रेरी का इस्तेमाल करने की अनुमति नहीं मिलती.

  • किसी कॉम्पोनेंट पर जाने और उसका कोड कॉपी करने के लिए, आपको अतिरिक्त क्लिक करने पड़ते हैं. “Tabs component CC Vocabulary” जैसी किसी चीज़ को Google पर खोजने पर, आपको वह जानकारी नहीं मिलती जो आपको चाहिए. दस्तावेज़ गाइड में मौजूद खोज विकल्प से UX को काफ़ी बेहतर बनाया जा सकेगा.

  • कॉम्पोनेंट के बारे में ज़्यादा जानकारी देने वाला टेक्स्ट. इसमें ऐसी जानकारी शामिल होती है जो साफ़ तौर पर नहीं दिखती.

  • लाइव रन का विकल्प नहीं है. JSFiddle जैसी कई साइटों को, लाइव रन की सुविधा मिलती है. इसकी मदद से डेवलपर, पूरे ऐप्लिकेशन को चलाए बिना कॉम्पोनेंट के बारे में जान सकते हैं, ताकि वह काम कर रहा हो.

समस्या का हल

इस समस्या को हल करने के कई तरीके हैं. हालांकि, हम यहां कुछ विषयों पर बात करेंगे और आखिर में अपना आखिरी समाधान बता रहे हैं:-

= Readthedocs का इस्तेमाल करना readthedocs ओपन सोर्स लाइब्रेरी के लिए दस्तावेज़ लिखने का एक अच्छा तरीका है. यह स्फ़िंक्स पर आधारित है, जो कि Python दस्तावेज़ टूल है.

फ़ायदे:

1. दस्तावेज़ जनरेट करने का एक ऐसा तरीका जिसे आम तौर पर स्वीकार किया जाता है. इसका इस्तेमाल Ethereum (Solidity) जैसे संगठन करते हैं.
2. सही तरीके से व्यवस्थित किया गया दस्तावेज़.
3. मुफ़्त स्टैटिक होस्टिंग.

नुकसान:

1. स्टाइलिंग पर पूरा कंट्रोल नहीं होता.

= स्फ़िंक्स का इस्तेमाल करना हम मूल रूप से दस्तावेज़ के हिस्से के लिए भी sphinx का इस्तेमाल कर सकते हैं, यह हमारे सभी मकसद के लिए अच्छी सुविधाएं देता है.

फ़ायदे:

1. दस्तावेज़ बनाने के लिए, Python का सबसे लोकप्रिय टूल.
2. इसमें दस्तावेज़ों को खोजने की सुविधा भी है.
3. डिफ़ॉल्ट सीएसएस को कस्टम सीएसएस से बदला जा सकता है. साथ ही, .rst फ़ाइलों का इस्तेमाल करके, एचटीएमएल पर कुछ कंट्रोल किया जा सकता है.

नुकसान:

1. इसमें Python और रीस्ट्रक्चर्ड टेक्स्ट फ़ॉर्मैट (.rst) में कोडिंग शामिल होगी, जो प्रोजेक्ट के लिए सुझाई गई भाषाओं से अलग होगी.

= Jekyll थीम का इस्तेमाल करना Jekyll थीम, GitHub पेजों में इंटिग्रेट की जाती हैं. साथ ही, पहले से मौजूद टेंप्लेट भी होते हैं, जिन्हें अपनी ज़रूरतों के हिसाब से पसंद के मुताबिक बनाया जा सकता है.

फ़ायदे:

1. सभी कामों के लिए, पहले से तैयार दस्तावेज़ की थीम.
2. डिफ़ॉल्ट सीएसएस और स्टाइल को कस्टम सीएसएस और स्टाइल से बदला जा सकता है. साथ ही, एचटीएमएल को भी कंट्रोल किया जा सकता है.
3. पेज बनाने के लिए, Primer की डिफ़ॉल्ट सीएसएस को खींचता है.
4. GitHub पेजों के साथ आसानी से इंटिग्रेशन.

नुकसान:

1. हो सकता है कि दस्तावेज़ को सबसे सही तरीके से व्यवस्थित न किया जा सके.

=GitHub पेजों का इस्तेमाल करना स्टैंडर्ड GitHub पेजों का इस्तेमाल करके, अपनी स्टैटिक साइट (एचटीएमएल, सीएसएस, JS) बनाएं.

फ़ायदे:

1. सवाल में शामिल ज़्यादातर चीज़ों पर पूरा कंट्रोल.
2. लेआउट, रंग, और स्टाइल तय करने में ज़्यादा से ज़्यादा विकल्प.
3. शब्दावली के कॉम्पोनेंट का आसानी से इस्तेमाल किया जा सकता है.
4. कोड स्निपेट और लाइव रन लिंक को आसानी से एम्बेड किया जा सकता है.

नुकसान:

1. इसमें ज़्यादा समय लग सकता है.

= हरूपद का इस्तेमाल करना यह इसके बजाय एक वैकल्पिक मार्कडाउन समाधान देता है.

फ़ायदे:

1. इसमें कम से कम कोडिंग की ज़रूरत होगी.
2. इस कोर्स में, दस्तावेज़ों को सही तरीके से लिखने पर फ़ोकस किया जाएगा.

नुकसान:

1. सीएसएस पर कंट्रोल न होना.
2. हो सकता है कि कम्यूनिटी से मिलने वाली सहायता सबसे अच्छी न हो.
3. हो सकता है कि यह MDX के साथ काम न करे.

= MKDocs का इस्तेमाल करना इससे मार्कडाउन के लिए, कोई दूसरा विकल्प मिलता है.

फ़ायदे:

1. इसमें कम से कम कोडिंग की ज़रूरत होगी.
2. ज़्यादा लिखें, कम कोड लिखें.

नुकसान:

1. सीएसएस पर कंट्रोल न होना.
2. हो सकता है कि कम्यूनिटी से मिलने वाली सहायता सबसे अच्छी न हो.
3. Python का इस्तेमाल करता है. इसके लिए, Amazon S3 इंस्टेंस को स्पिन अप करने की ज़रूरत पड़ सकती है.

= VueJS +StorybookJS का इस्तेमाल करना इस तरीके का इस्तेमाल, आम तौर पर Vocabulary और उसके मिलते-जुलते रिपॉज़िटरी में किया जाता है.

फ़ायदे:

1. पिछले काम के अनुभवों को ध्यान में रखते हुए, हमने ऐसी टेक्नोलॉजी का इस्तेमाल किया है जो ठीक से काम करेंगी.
2. कोड बेस के बारे में जानकारी होनी चाहिए.
3. इस जगह पर ऐसा कोई टेक्नोलॉजी नहीं है जो बेहतर हो.

नुकसान:

1. एक ही काम के लिए, आसान विकल्प भी मौजूद हो सकते हैं.

आखिर में, मुझे लगता है कि VueJS+Storybook (एचटीएमएल,सीएसएस,जेएस) का तरीका सबसे सही है. ऐसा इसलिए, क्योंकि मुझे यह तरीका भी पसंद है. हालांकि, इसका यह भी मतलब है कि हम इस ऐप्लिकेशन को डेवलप करने में पूरी तरह से शामिल नहीं होंगे. सीसी-वॉकेबुलरी कॉम्पोनेंट का इस्तेमाल करना भी आसान होगा. हालांकि, दस्तावेज़ के स्ट्रक्चर का फ़ैसला लेने के लिए, हमें readthedocs दस्तावेज़ में कॉन्टेंट को सबहेडिंग के बीच बांटने के तरीके पर ज़रूर ध्यान देना चाहिए. मुझे Semantic-UI वेबसाइट (StoryBook का इस्तेमाल करने वाली) पसंद आई, क्योंकि इसका लुक कम से कम है और कुछ ही क्लिक के बाद, किसी को भी यह आसानी से पता चल सकता है कि उसे क्या चाहिए. मैंने Semantic-UI के अलावा, Material Design, Primer, Bootstrap, Carbon Design वगैरह को भी देखा. इनका इस्तेमाल, अपने काम के लिए यूज़र इंटरफ़ेस (यूआई) की स्टाइल से जुड़ी गाइड और डिज़ाइन सिस्टम के तौर पर किया जा सकता है. इसके लिए, Jekyll की पहले से तैयार दस्तावेज़ थीम भी देखी जा सकती हैं.