इस पेज पर Google Docs के सीज़न के लिए स्वीकार किए गए एक तकनीकी लेखन प्रोजेक्ट की जानकारी है.
प्रोजेक्ट की खास जानकारी
- ओपन सोर्स संगठन:
- क्लाउड नेटिव कंप्यूटिंग फ़ाउंडेशन (सीएनसीएफ़)
- तकनीकी लेखक:
- श्रीति
- प्रोजेक्ट का नाम:
- एसएमआई और उससे जुड़ी सेवा में लगे मेश के दस्तावेज़ों को बेहतर बनाना
- प्रोजेक्ट की अवधि:
- मानक अवधि (तीन महीने)
प्रोजेक्ट का विवरण
सर्विस मेश टेक्नोलॉजी का मुख्य मकसद सुरक्षा, मैनेजमेंट, और निगरानी से जुड़ी आपकी सभी ज़रूरतों को पूरा करके, सेवाओं की बढ़ती संख्या को बेहतर बनाना है. सर्विस मेश इंटरफ़ेस (एसएमआई), सबसे सामान्य सर्विस मेश इस्तेमाल के मामलों के लिए एपीआई का सेट (ट्रैफ़िक नीति, टेलीमेट्री, और शिफ़्टिंग) तय करता है. साथ ही, सेवा मेश के बीच काम करता है. ये माइक्रोसर्विस एनवायरमेंट में सेवा-से-सेवा के बीच कम्यूनिकेशन को मैनेज करने के लिए इन्फ़्रास्ट्रक्चर लेयर हैं. इन इंटरफ़ेस के अलग-अलग स्टैंडर्ड तय करने से, असली उपयोगकर्ता को बेहतर अनुभव मिलेगा. इसलिए, एसएमआई और इससे जुड़ी सेवा के लिए यह आने वाले समय का लक्ष्य है.
मौजूदा स्थिति:
उपयोगकर्ता गाइड: एसएमआई एक नया सैंडबॉक्स प्रोजेक्ट है, जिसे अप्रैल 2020 में सीएनसीएफ़ को दान किया गया था. इस वजह से, प्रोजेक्ट में असली उपयोगकर्ता के दस्तावेज़ मौजूद नहीं हैं. Meshery, सेवा मैनेजमेंट का एक प्लैटफ़ॉर्म है. इसमें हर तरह की सेवाओं के लिए परफ़ॉर्मेंस की तुलना की जाती है. ये सेवाएं अलग-अलग मेश की परफ़ॉर्मेंस को अपनाने, कॉन्फ़िगरेशन, ऑपरेशन, और मैनेजमेंट की सुविधा देती हैं. साथ ही, इसमें किसी भी सर्विस मेश के ऊपर चल रहे ऐप्लिकेशन से मेट्रिक का कलेक्शन और डिसप्ले शामिल होता है. इसलिए, हम मेशरी के लिए एक गाइड के साथ शुरुआत करना चाहते हैं. यह एसएमआई (SMI) उपयोगकर्ता समुदाय के लिए एक शुरुआती बिंदु की तरह काम करेगा.
उपयोगकर्ता ट्यूटोरियल: मौजूदा एसएमआई प्लैटफ़ॉर्म में: 'लर्निंग' टूल SMI और इससे जुड़ी सर्विस मेश के इस्तेमाल और फ़ायदों को दिखाने के लिए, Meshery बेहतरीन ऐप्लिकेशन है. इसलिए, SMI की सुविधाएं दिखाने के लिए, मैं इसे बेस टूल के तौर पर इस्तेमाल कर पा रही हूं.
एपीआई दस्तावेज़: फ़िलहाल, यह मौजूद नहीं है. एसएमआई और कई मिलते-जुलते प्रोजेक्ट के एपीआई एंडपॉइंट एक प्लैटफ़ॉर्म पर तय किए जाते हैं. उदाहरण के लिए, Meshery के एंडपॉइंट, server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) पर तय किए गए हैं, लेकिन न तो इनके बारे में किसी तरह की टिप्पणी की जा सकती है और न ही इन्हें बाहर के किसी दस्तावेज़ में शामिल किया जा सकता है. इसे एपीआई की मदद से काम के दस्तावेज़ की मदद से हल किया जा सकता है. साथ ही, इसे बेहतर बनाया जा सकता है. इसके लिए, उपयोगकर्ताओं के लिए, एंडपॉइंट की जांच करने और इसकी सुविधाओं की झलक देखने के तरीके जोड़े जा सकते हैं.
विश्लेषण:
उपयोगकर्ता ट्यूटोरियल इस तरह बनाए जाते हैं कि उपयोगकर्ता को सॉफ़्टवेयर से जुड़ने और उसे टेस्ट करने में मदद मिल सके. ये इंटरैक्टिव और आकर्षक होने चाहिए, ताकि लोगों का ध्यान खींचा जा सके. साथ ही, इन्हें आसानी से इस्तेमाल किया जा सकता है.
हालांकि, उपयोगकर्ता गाइड लिखने या होस्ट करने के लिए, ज़्यादा वयस्क फ़ॉर्मैट की सलाह दी जाती है, क्योंकि उपयोगकर्ता गाइड अक्सर रेफ़रंस गाइड के तौर पर या समस्याओं को तुरंत हल करने की जगह के तौर पर काम करती हैं. इंटरैक्टिव होने के बजाय, उन्हें अच्छी तरह से बनाया जाना चाहिए. साथ ही, इन्हें बेहतर तरीके से समझने, एक-दूसरे से बात करने, और अच्छे यूज़र फ़्लो पर ध्यान देने की ज़रूरत है.
इसका एक संभावित हल यह होगा कि जेकिल की मदद से, Google Codelabs और एक स्वतंत्र उपयोगकर्ता गाइड का इस्तेमाल करके अलग से उपयोगकर्ता ट्यूटोरियल बनाए जाएं. इसके बाद, उन्हें एपीआई दस्तावेज़ के साथ जोड़ा जाए, ताकि असली उपयोगकर्ता और आने वाले समय में सहयोगियों को एक बेहतर अनुभव दिया जा सके.
टारगेट ऑडियंस: एसएमआई प्रोजेक्ट, अपने सभी प्रोजेक्ट के लिए डिप्लॉयमेंट और ऑपरेशनल तरीके, सीखने के माहौल की सुविधा, और परफ़ॉर्मेंस मानदंड उपलब्ध कराते हैं. यह व्यक्तियों और संगठनों, दोनों के लिए है.
उपयोगकर्ता गाइड: मुझे शुरुआत करने वाले उपयोगकर्ताओं को टारगेट करना होगा. मुझे इस बात की कोई उम्मीद नहीं है कि उपयोगकर्ता को पहले से कोई आईटी जानकारी है या नहीं. टारगेट: शुरुआत करने वाले उपयोगकर्ता वजह: मुख्य रूप से इसे एक बड़ी रेफ़रंस गाइड के तौर पर इस्तेमाल किया जाता है, जिसे समय-समय पर अपडेट करना पड़ता है. इसमें पूरी जानकारी और मददगार सलाह शामिल होंगी. इससे यह पक्का किया जा सकेगा कि उपयोगकर्ता के पास वह सारी जानकारी हो जो उसे सर्विस मेश सेट अप करने और उस पर काम करने के लिए चाहिए. जहां भी ज़रूरत होगी, वीडियो, तस्वीरें, स्क्रीनशॉट, और GIF जोड़कर गाइड को ज़्यादा दिलचस्प और इस्तेमाल में आसान बनाया जाएगा.
उपयोगकर्ता ट्यूटोरियल: टारगेट: शुरुआत करने वाले उपयोगकर्ता वजह: ट्यूटोरियल को दिलचस्प और आकर्षक बनाने पर ध्यान दिया जाएगा, ताकि उपयोगकर्ता का ध्यान खींचा जा सके और सॉफ़्टवेयर का आसानी से टेस्ट किया जा सके. इससे सर्विस मेश इंटरफ़ेस को बेहतर तरीके से समझने में मदद मिलेगी.
एपीआई एंडपॉइंट दस्तावेज़: टारगेट: बेहतर उपयोगकर्ता वजह: यह सेक्शन, सर्विस मेश की ज़्यादा जटिल सुविधाओं के इस्तेमाल पर फ़ोकस करता है. ये उन उपयोगकर्ताओं के हित में है जिन्हें आईटी की बुनियादी जानकारी होती है. जानकार उपयोगकर्ताओं को छोटे ट्यूटोरियल चाहिए होते हैं. ज़रूरत पड़ने पर इनका इस्तेमाल रेफ़रंस गाइड के तौर पर भी किया जा सकता है. एंडपॉइंट के दस्तावेज़ इस तरह से लिखे जाने चाहिए, ताकि इसे अपडेट करने में आसानी हो. साथ ही, यह पक्का किया जा सके कि यह सटीक या एक जैसा हो. आम तौर पर, यह अपने-आप काम करने वाली प्रक्रिया होनी चाहिए.
संसाधन: उपयोगकर्ता ट्यूटोरियल: Google Developers कोडलैब (कोड बनाना सीखना) - इसका इस्तेमाल, असली उपयोगकर्ता के लिए इंटरैक्टिव और बेहतर ट्यूटोरियल बनाने के लिए किया जाता है. फ़ायदे: - सैंडबॉक्स ट्यूटोरियल बना सकते हैं. - सोच-समझकर फ़ैसला लेने वाली हैं. - यह लेख, Google Docs का इस्तेमाल करके लिखा गया है. साथ ही, इसमें Markdown टेक्स्ट का इस्तेमाल किया जा सकता है. - Google Analytics का इस्तेमाल करके निगरानी की जा सकती है - उपयोगकर्ता ट्रैफ़िक को आसानी से देखा जा सकता है. - इस्तेमाल में आसान. आकर्षक ट्यूटोरियल ऐसे बनाता है जिनकी मदद से, उपयोगकर्ता बिना किसी सीधे तौर पर सॉफ़्टवेयर इस्तेमाल कर सकते हैं.
Google Codelabs को CLaaT (Codelabs as a Thing) प्रोजेक्ट का इस्तेमाल करके बेहतर और आसानी से डिप्लॉय किया जा सकता है - यह एक ऐसा प्रोग्राम है जो एक कमांड-लाइन टूल देता है. इसका इस्तेमाल, Google Doc में लिखे गए ट्यूटोरियल को कोडलैब (एचटीएमएल) फ़ॉर्मैट में बदलने के लिए किया जाता है.
उपयोगकर्ता गाइड: Jekyll - meshery.io के लिए मौजूदा दस्तावेज़, जो यहां देखा जा सकता है उसे Jekyll पर होस्ट किया गया है और इसमें Docsy Jekyll की थीम का इस्तेमाल किया गया है. यह, होस्ट के लिए तैयार और स्टैटिक वेबसाइटें बनाने के लिए Markdown, liquid, एचटीएमएल, और सीएसएस का इस्तेमाल करता है. साथ ही, यह Ruby के डेवलपमेंट एनवायरमेंट पर चलता है. फ़ायदे: - सीधे GitHub पर डेटा स्टोर करने की जगहों से साइटों को होस्ट किया जा सकता है. - बहुत सक्रिय समुदाय वाला यह प्रोजेक्ट अच्छी तरह से काम करता है - उपयोगकर्ता गाइड और बेहतर बनाने की सुविधाएं, किसी दूसरे प्लैटफ़ॉर्म पर माइग्रेट किए बिना बस मौजूदा एसएमआई और मेशरी दस्तावेज़ में जोड़ी जा सकती हैं.
एपीआई दस्तावेज़: Swager का इस्तेमाल, SMI और Meshery के लिए एपीआई दस्तावेज़ बनाने में किया जाएगा. हालांकि, स्वैगर के विकल्प के तौर पर Swiggo का इस्तेमाल किया जाएगा. यह API दस्तावेज़ लिखने के लिए एक शानदार समाधान है. फ़ायदे: - आपके एपीआई डिज़ाइन से जुड़े दस्तावेज़: पक्का करता है कि जैसे-जैसे आपका एपीआई बेहतर होता जाए, आपके दस्तावेज़ अप-टू-डेट रहें. - आपके एपीआई डिज़ाइन से दस्तावेज़: एपीआई परिभाषाओं की मदद से अपने-आप जनरेट किया जा सकता है. - दस्तावेज़ के एक से ज़्यादा वर्शन बनाए रखें - पसंद के मुताबिक एपीआई डिज़ाइन बनाएं
प्रोजेक्ट के लक्ष्य: - मेशरी का इस्तेमाल एक टूल के तौर पर किया जाता है. इसके लिए, Google डेवलपर कोडलैब का इस्तेमाल करके एसएमआई और उससे जुड़ी सेवाओं के लिए इंटरैक्टिव ट्यूटोरियल बनाए जा सकते हैं. - सेवा मेश के लिए जेकिल का इस्तेमाल करके असली उपयोगकर्ता के लिए एक गाइड बनाएं. - एसएमआई के लिए एपीआई एंडपॉइंट दस्तावेज़ जनरेट करने के लिए, स्वैगर का इस्तेमाल करें. - प्रोजेक्ट को कम्यूनिटी के हिसाब से बनाएं, ताकि आने वाले समय में और मौजूदा उपयोगकर्ता या डेवलपर, एसएमआई समुदाय के दिशा-निर्देशों और मॉडरेशन में, प्रोजेक्ट को आसानी से जोड़ सकें.
टाइमलाइन: सुझाई गई टाइमलाइन यहां देखी जा सकती है: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#बुकमार्क=kix.j1b6m64eubsl
स्ट्रक्चर: यूज़र गाइड का सुझाया गया स्ट्रक्चर यहां देखा जा सकता है: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
यह प्रोजेक्ट ही क्यों? सर्विस मेश कम्यूनिटी का दायरा काफ़ी तेज़ी से बढ़ रहा है. हाल ही में, इसे सैंडबॉक्स प्रोजेक्ट के तौर पर सीएनसीएफ़ के साथ इंटिग्रेट किया गया है. हालांकि, इस प्रोजेक्ट में असली उपयोगकर्ताओं और डेवलपर, दोनों के लिए दस्तावेज़ की कमी हो रही है. मैंने पहले कई तरह के सर्विस मेश का इस्तेमाल किया है, जिनमें इमोजीVoto ऐप के साथ linkerD, अपने Bookinfo ऐप्लिकेशन के साथ Istio, और Hahicorp's Consul शामिल हैं. मैंने एसएमआई ट्रैफ़िक स्प्लिट को भी आज़माया है और अपने सर्विस मेश कॉन्फ़िगरेशन पर पुष्टि करने के कई नियम लागू किए हैं. सीखने की यह प्रक्रिया दिलचस्प होने के साथ-साथ तकनीकी भी है. यह नए उपयोगकर्ताओं के साथ-साथ डेवलपर के लिए भी मुश्किल हो सकता है, क्योंकि वे सर्विस मेश कम्यूनिटी में अपना पहला कदम रखना चाहते हैं. इसके अलावा, वे अपने निजी या पेशेवर प्रोजेक्ट के लिए सर्विस मेश का इस्तेमाल कर सकते हैं. मुझे इस अंतर को कम करना है. ऐसा करने के लिए, हम सही गाइड और ट्यूटोरियल की मदद से ही काम कर सकते हैं.