इस पेज पर, तकनीकी लेखन वाले उस प्रोजेक्ट की जानकारी दी गई है जिसे Google Season of Docs के लिए स्वीकार किया गया है.
प्रोजेक्ट की खास जानकारी
- ओपन सोर्स संगठन:
- Cloud Native Computing Foundation (CNCF)
- टेक्निकल राइटर:
- श्रीति
- प्रोजेक्ट का नाम:
- एसएमआई और उससे जुड़े सेवा मेश के दस्तावेज़ को बेहतर बनाना
- प्रोजेक्ट की अवधि:
- स्टैंडर्ड लंबाई (तीन महीने)
प्रोजेक्ट का विवरण
सर्विस मेश टेक्नोलॉजी का मकसद, सुरक्षा, मैनेजमेंट, और निगरानी से जुड़ी आपकी सभी ज़रूरतों को पूरा करके, सेवाओं की बढ़ती हुई संख्या को बेहतर बनाना है. सर्विस मेश इंटरफ़ेस (एसएमआई), सर्विस मेश के इस्तेमाल के सबसे सामान्य उदाहरणों (ट्रैफ़िक नीति, टेलीमेट्री, और शिफ़्टिंग) के लिए एपीआई का एक सेट तय करता है. इसकी मदद से, सर्विस मेश के बीच काम करने की सुविधा मिलती है. मेश, माइक्रोसर्विस एनवायरमेंट में सर्विस-टू-सर्विस कम्यूनिकेशन को मैनेज करने के लिए, खास इन्फ़्रास्ट्रक्चर लेयर हैं. इन इंटरफ़ेस को स्टैंडर्ड बनाने से, असली उपयोगकर्ताओं को बेहतर अनुभव मिलेगा. इसलिए, SMI और उससे जुड़े सेवा मेश के लिए, आने वाले समय में यह एक लक्ष्य होगा.
मौजूदा स्थिति:
उपयोगकर्ता गाइड: SMI एक नया सैंडबॉक्स प्रोजेक्ट है. इसे अप्रैल 2020 में CNCF को दान किया गया था. इस वजह से, प्रोजेक्ट में असली उपयोगकर्ता के लिए दस्तावेज़ मौजूद नहीं हैं. Meshery, सेवा मैनेजमेंट प्लेन है. इसमें सभी तरह की सेवाओं के लिए परफ़ॉर्मेंस की बेंचमार्किंग की सुविधा होती है. इससे अलग-अलग सेवा मेश की परफ़ॉर्मेंस को अपनाने, कॉन्फ़िगर करने, ऑपरेट करने, और मैनेज करने में मदद मिलती है. साथ ही, किसी भी सेवा मेश पर चल रहे ऐप्लिकेशन की मेट्रिक को इकट्ठा और दिखाने की सुविधा भी मिलती है. इसलिए, मैं Meshery के लिए एक गाइड से शुरुआत करना चाहूंगा. यह एसएमआई की पूरी उपयोगकर्ता कम्यूनिटी के लिए शुरुआती पॉइंट के तौर पर काम करेगी.
उपयोगकर्ता के लिए ट्यूटोरियल: मौजूदा एसएमआई प्लैटफ़ॉर्म में: सैंपल ऐप्लिकेशन, Learn Layer5, फ़िलहाल एसएमआई के लिए लर्निंग डिवाइस के तौर पर काम करता है. साथ ही, एसएमआई स्पेसिफ़िकेशन की पुष्टि करने के लिए सैंपल ऐप्लिकेशन के तौर पर भी काम करता है. हालांकि, एसएमआई प्रोजेक्ट में असली उपयोगकर्ता के लिए ट्यूटोरियल नहीं हैं. प्रोजेक्ट की तकनीकी प्रकृति की वजह से, यह एक गंभीर समस्या है. SMI और उससे जुड़े सेवा मेश के फ़ायदों और इस्तेमाल को दिखाने के लिए, Meshery सबसे सही ऐप्लिकेशन है. इसलिए, मैं SMI की सुविधाओं को दिखाने के लिए, इसे बेस टूल के तौर पर इस्तेमाल करूंगा.
एपीआई दस्तावेज़: फ़िलहाल, यह उपलब्ध नहीं है. SMI और उससे जुड़े कई प्रोजेक्ट के एपीआई एंडपॉइंट, किसी प्लैटफ़ॉर्म पर तय किए गए हैं. उदाहरण के लिए, Meshery के एंडपॉइंट, server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) पर तय किए गए हैं. हालांकि, इन पर अच्छी तरह से टिप्पणी नहीं की गई है और न ही इनका बाहरी दस्तावेज़ उपलब्ध है. एपीआई के काम के दस्तावेज़ों की मदद से, इस समस्या को हल किया जा सकता है. साथ ही, उपयोगकर्ताओं को एंडपॉइंट की जांच करने और उसकी सुविधाओं की झलक देखने के तरीके जोड़कर, इस समस्या को और बेहतर बनाया जा सकता है.
विश्लेषण:
उपयोगकर्ता ट्यूटोरियल इस तरह बनाए जाते हैं कि उपयोगकर्ता उनसे जुड़ सकें और सॉफ़्टवेयर की जांच कर सकें. उपयोगकर्ता का ध्यान खींचने के लिए, उन्हें इंटरैक्टिव और आकर्षक होना चाहिए. साथ ही, सबसे ज़रूरी बात यह है कि उन्हें इस्तेमाल करना आसान होना चाहिए.
हालांकि, उपयोगकर्ता गाइड लिखने या होस्ट करने के लिए, बेहतर फ़ॉर्मैट का इस्तेमाल करना बेहतर होगा. ऐसा इसलिए, क्योंकि उपयोगकर्ता गाइड अक्सर रेफ़रंस गाइड के तौर पर काम करती हैं या समस्याओं को तुरंत ठीक करने में मदद करती हैं. इनमें इंटरैक्टिव कॉन्टेंट के बजाय, अच्छी तरह से व्यवस्थित किया गया कॉन्टेंट होना चाहिए. साथ ही, इनमें साफ़ तौर पर जानकारी देने, एक-दूसरे से जुड़े कॉन्टेंट, और उपयोगकर्ताओं के फ़्लो को बेहतर बनाने पर फ़ोकस किया जाना चाहिए.
इस समस्या का एक संभावित समाधान यह हो सकता है कि Google Codelabs का इस्तेमाल करके, उपयोगकर्ताओं के लिए अलग-अलग ट्यूटोरियल बनाए जाएं. साथ ही, Jekyll की मदद से उपयोगकर्ताओं के लिए एक अलग गाइड बनाई जाए. आखिर में, इन ट्यूटोरियल और गाइड को एपीआई दस्तावेज़ के साथ इंटिग्रेट किया जाए, ताकि असली उपयोगकर्ताओं और आने वाले समय में साथ काम करने वाले लोगों, दोनों को बेहतर अनुभव दिया जा सके.
टारगेट ऑडियंस: SMI प्रोजेक्ट, अपने सभी प्रोजेक्ट के लिए डिप्लॉयमेंट और ऑपरेशनल तरीकों, सीखने के माहौल, और परफ़ॉर्मेंस के मानदंड उपलब्ध कराते हैं. यह सुविधा, लोगों और संगठनों, दोनों के लिए उपलब्ध है.
उपयोगकर्ता गाइड: मैं शुरुआती उपयोगकर्ताओं को टारगेट करूंगा. इसमें यह नहीं माना जाएगा कि उपयोगकर्ता के पास पहले से आईटी की जानकारी है. टारगेट: शुरुआती उपयोगकर्ता वजह: इसका इस्तेमाल मुख्य रूप से एक बड़ी रेफ़रंस गाइड के तौर पर किया जाता है. इसे समय के साथ अपडेट करना होगा. इसमें पूरी जानकारी और मददगार सलाह शामिल होंगी, ताकि यह पक्का किया जा सके कि उपयोगकर्ता के पास सर्विस मेश सेट अप करने और उसके साथ काम करने के लिए सभी ज़रूरी जानकारी मौजूद है. ज़रूरत पड़ने पर, वीडियो, फ़ोटो, स्क्रीनशॉट, और GIF जोड़कर, गाइड को ज़्यादा दिलचस्प और उपयोगकर्ता के हिसाब से बनाया जाएगा.
उपयोगकर्ता के लिए ट्यूटोरियल: टारगेट: शुरुआती उपयोगकर्ता वजह: ट्यूटोरियल को दिलचस्प और आकर्षक बनाने पर फ़ोकस किया जाएगा, ताकि उपयोगकर्ता का ध्यान बना रहे. साथ ही, सॉफ़्टवेयर को आसानी से टेस्ट किया जा सके. इससे, Service Mesh इंटरफ़ेस को बेहतर तरीके से समझने में मदद मिलेगी.
एपीआई एंडपॉइंट का दस्तावेज़: टारगेट: बेहतर सुविधाओं वाले उपयोगकर्ता वजह: इस सेक्शन में, सेवा मेश की ज़्यादा जटिल सुविधाओं का इस्तेमाल करने पर फ़ोकस किया गया है. यह सुविधा, आईटी के बुनियादी ज्ञान वाले बेहतर उपयोगकर्ताओं के लिए ज़्यादा काम की है. अनुभवी उपयोगकर्ताओं को कम शब्दों वाले ट्यूटोरियल की तलाश होती है. ज़रूरत पड़ने पर, इन ट्यूटोरियल का इस्तेमाल रेफ़रंस गाइड के तौर पर भी किया जा सकता है. एंडपॉइंट दस्तावेज़ को इस तरह से लिखा जाना चाहिए कि उसे सटीक या एक जैसा बनाए रखते हुए आसानी से अपडेट किया जा सके. यह प्रोसेस ऑटोमेटेड होनी चाहिए.
संसाधन: उपयोगकर्ता के लिए ट्यूटोरियल: Google Developers Codelab - इसका इस्तेमाल, इंटरैक्टिव और बेहतरीन उपयोगकर्ता ट्यूटोरियल बनाने के लिए किया जाता है. फ़ायदे: - सैंडबॉक्स ट्यूटोरियल बनाए जा सकते हैं. - इस कार्यक्रम को जल्द से जल्द पूरा करते हैं. - Google Docs का इस्तेमाल करके लिखा गया हो और Markdown टेक्स्ट के साथ काम करता हो. - Google Analytics का इस्तेमाल करके निगरानी की जा सकती है - उपयोगकर्ता ट्रैफ़िक को आसानी से देखा जा सकता है. - इस्तेमाल में आसान. ये खूबसूरत ट्यूटोरियल वीडियो बनाते हैं. इनसे लोगों को सीधे तौर पर सॉफ़्टवेयर से जुड़ने में मदद मिलती है. इसके लिए, उन्हें सीधे तौर पर निवेश नहीं करना पड़ता.
Google Codelabs को बेहतर बनाया जा सकता है और CLaaT (Codelabs as a Thing) प्रोजेक्ट का इस्तेमाल करके, उन्हें आसानी से डिप्लॉय किया जा सकता है. यह एक ऐसा प्रोग्राम है जो कमांड-लाइन टूल उपलब्ध कराता है. इसका इस्तेमाल, Markdown का इस्तेमाल करके Google दस्तावेज़ में लिखे गए ट्यूटोरियल को Codelabs (HTML) फ़ॉर्मैट में बदलने के लिए किया जाता है.
उपयोगकर्ता गाइड: Jekyll - meshery.io के लिए मौजूदा दस्तावेज़, Jekyll पर होस्ट किए जाते हैं. इन्हें यहां देखा जा सकता है. साथ ही, इनमें Docsy Jekyll थीम का इस्तेमाल किया जाता है. यह होस्ट, स्टैटिक वेबसाइटें बनाने के लिए Markdown, लिक्विड, एचटीएमएल, और सीएसएस का इस्तेमाल करता है. साथ ही, यह Ruby डेवलपमेंट एनवायरमेंट पर काम करता है. फ़ायदे: - सीधे GitHub डेटा स्टोर करने की जगहों से साइटों को होस्ट किया जा सकता है. - यह एक ऐसा प्रोजेक्ट है जिसे ज़्यादातर लोग इस्तेमाल करते हैं और इसकी कम्यूनिटी भी बहुत सक्रिय है - उपयोगकर्ता गाइड और बेहतर सुविधाओं को, किसी दूसरे प्लैटफ़ॉर्म पर माइग्रेट किए बिना, मौजूदा SMI और Meshery दस्तावेज़ में आसानी से जोड़ा जा सकता है.
एपीआई दस्तावेज़: SMI और Meshery के लिए एपीआई दस्तावेज़ बनाने के लिए, Swagger (इसके अलावा, Swaggo) का इस्तेमाल किया जाएगा. यह एपीआई दस्तावेज़ लिखने का बेहतरीन तरीका है. फ़ायदे: - आपके एपीआई डिज़ाइन से दस्तावेज़: इससे यह पक्का होता है कि आपका दस्तावेज़, एपीआई के अपडेट होने के साथ-साथ अप-टू-डेट रहे. - आपके एपीआई डिज़ाइन से दस्तावेज़: एपीआई की परिभाषाओं से अपने-आप जनरेट हो सकता है. - दस्तावेज़ के कई वर्शन बनाए रखना - पसंद के मुताबिक बनाए गए एपीआई डिज़ाइन
प्रोजेक्ट के लक्ष्य: - Google Developer Codelabs का इस्तेमाल करके, एसएमआई और उससे जुड़ी सेवा मेश के लिए, असली उपयोगकर्ताओं के लिए इंटरैक्टिव ट्यूटोरियल बनाएं. इसके लिए, Meshery को टूल के तौर पर इस्तेमाल करें. - सेवा मेश के लिए Jekyll का इस्तेमाल करके, असली उपयोगकर्ता के लिए गाइड बनाएं. - SMI के लिए एपीआई एंडपॉइंट का दस्तावेज़ जनरेट करने के लिए, Swagger का इस्तेमाल करें. - प्रोजेक्ट कम्यूनिटी को आगे की कार्रवाई के लिए प्रेरित करें, ताकि आने वाले समय में और मौजूदा उपयोगकर्ता या डेवलपर, एसएमआई कम्यूनिटी के मार्गदर्शन और मॉडरेशन में इसमें आसानी से जुड़ सकें.
टाइमलाइन: प्रस्तावित टाइमलाइन यहां देखी जा सकती है: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
स्ट्रक्चर: उपयोगकर्ता गाइड का सुझाया गया स्ट्रक्चर यहां देखा जा सकता है: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
यह प्रोजेक्ट क्यों? सर्विस मेश कम्यूनिटी तेज़ी से बढ़ रही है. इसकी वजह यह है कि इसे हाल ही में CNCF में सैंडबॉक्स प्रोजेक्ट के तौर पर इंटिग्रेट किया गया है. हालांकि, इस प्रोजेक्ट में, असली उपयोगकर्ताओं और डेवलपर, दोनों के लिए दस्तावेज़ों की भारी कमी है. मैंने पहले कई तरह की सर्विस मेश के साथ गेम खेला है, जिनमें इमोजीVoto ऐप्लिकेशन के साथ linkerD, Istio के बुकinfo ऐप्लिकेशन, और Hashicorp’s Consul का लिंक है. मैंने एसएमआई ट्रैफ़िक के बंटवारे की सुविधा भी आज़मा ली है. साथ ही, अपने सेवा मेश कॉन्फ़िगरेशन पर पुष्टि करने के कई नियम लागू कर दिए हैं. सीखने की प्रोसेस दिलचस्प है, लेकिन बेहद तकनीकी है. इसलिए, यह सेवा मेश कम्यूनिटी में अपने पहले कदम रखने या अपने निजी या पेशेवर प्रोजेक्ट के लिए सेवा मेश का इस्तेमाल करने वाले नए उपयोगकर्ताओं और डेवलपर के लिए परेशानी हो सकती है. मैं इस अंतर को कम करना चाहता/चाहती हूं. ऐसा सिर्फ़ बेहतर और अच्छी तरह से तैयार की गई गाइड और ट्यूटोरियल की मदद से किया जा सकता है.