जीआरपीसी-गेटवे प्रोजेक्ट

इस पेज पर, तकनीकी लेखन वाले उस प्रोजेक्ट की जानकारी दी गई है जिसे Google Season of Docs के लिए स्वीकार किया गया है.

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

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

जीआरपीसी-गेटवे

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

iamrajiv

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

gRPC-Gateway की मौजूदा Docs साइट को फिर से तैयार करना

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

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

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

संक्षेप:

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

इस लेख को लिखने के समय, gRPC-Gateway के रिपॉज़िटरी को करीब 1,200 बार फ़ॉर्क किया गया है. साथ ही, 184 लोगों ने इस रिपॉज़िटरी में योगदान दिया है. इससे पता चलता है कि दुनिया भर में कई लोग gRPC-Gateway का इस्तेमाल करते हैं. साथ ही, हो सकता है कि वे gRPC-Gateway का इस्तेमाल करने के तरीके के बारे में जानने के लिए, इसके उपयोगकर्ता दस्तावेज़ पढ़ें. हालांकि, gRPC-Gateway के उपयोगकर्ता के दस्तावेज़ और दस्तावेज़ों की साइट फ़िलहाल पुरानी और अधूरी है. gRPC-Gateway कम्यूनिटी इस प्रोजेक्ट का इस्तेमाल, मौजूदा दस्तावेज़ों की साइट को फिर से बनाने और उसे बेहतर बनाने के लिए करना चाहती है, ताकि असली उपयोगकर्ताओं को gRPC-Gateway का इस्तेमाल करते समय कोई परेशानी न हो.

मौजूदा स्थिति:

फ़िलहाल, gRPC-Gateway की दस्तावेज़ों वाली साइट में दो मुख्य समस्याएं हैं:-

• पहली समस्या यह है कि दस्तावेज़ों की वेबसाइट खराब और पुरानी है. इसका मतलब है कि साइट और थीम की स्टाइल और स्ट्रक्चर पुराना है, अधूरा है, नेविगेट करना या जानकारी ढूंढना मुश्किल है. साथ ही, इसमें दस्तावेज़ों की अच्छी वेबसाइट की कई सुविधाएं शामिल नहीं हैं. gRPC-Gateway की मौजूदा Docs साइट को फिर से तैयार करने में, वेबसाइट को स्टाइल करना, दस्तावेज़ खोजने जैसी सुविधाएं जोड़ना, वेबसाइट के यूज़र इंटरफ़ेस (यूआई) को बेहतर बनाना, ट्यूटोरियल और उदाहरणों को सही साइडबार में व्यवस्थित करना, और नए फ़्लोचार्ट और इमेज डिज़ाइन करके मौजूदा फ़्लोचार्ट और इमेज को अपडेट करना शामिल होगा. यह मेरा मुख्य लक्ष्य होगा और मेरा काम, मौजूदा Docs साइट को स्टाइल करने और उसका स्ट्रक्चर फिर से तैयार करने पर आधारित होगा.

• दूसरी समस्या, gRPC-Gateway के मौजूदा दस्तावेज़ों, ट्यूटोरियल, और उदाहरणों वगैरह को फिर से तैयार करने की ज़रूरत है. ऐसा करने के लिए, सभी फ़ाइलों में टाइपोग्राफ़ी और व्याकरण से जुड़ी गड़बड़ियों को हटाएं. साथ ही, Go स्निपेट को सही तरीके से अलाइन करें और Gofmt फ़ॉर्मैट के हिसाब से Go स्निपेट को फिर से तैयार करें. अगर ऐसा है, तो ज़रूरत पड़ने पर हम ज़्यादा दस्तावेज़, ट्यूटोरियल, और उदाहरण जोड़ सकते हैं. इसके अलावा, हम मौजूदा फ़ाइलों को रीफ़ैक्टर करने के बाद, उनका फिर से इस्तेमाल कर सकते हैं. यह मेरा सेकंडरी लक्ष्य है.इसे तब ही किया जाएगा, जब मैं अपना मुख्य लक्ष्य पूरा कर लूं. जैसे, Docs की मौजूदा साइट को डिज़ाइन करना और उसे फिर से बनाना.

मेरी सुझाई गई दस्तावेज़ों की साइट, मौजूदा साइट से बेहतर क्यों है?

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

gRPC-Gateway दस्तावेज़ में, इस तरीके और उदाहरण के बारे में अच्छी जानकारी दी गई है. हालांकि, यह अब भी पुरानी Jekyll थीम का इस्तेमाल कर रही है. आज के समय में, हमारे पास बेहतर एसएसजी (स्टैटिक साइट जनरेटर) Jekyll थीम हैं. साथ ही, पेजों को फिर से व्यवस्थित करने की ज़रूरत है. साथ ही, नए उदाहरण और ट्यूटोरियल जोड़कर, उपयोगकर्ताओं के लिए इसे ज़्यादा काम का बनाने की ज़रूरत है. साथ ही, पिछले कॉन्टेंट को अपडेट करके और फिर से लिखकर भी ऐसा किया जा सकता है.

सुझाए गए लक्ष्यों और आइडिया का स्ट्रक्चर और रोडमैप:

इस प्रोजेक्ट का मुख्य लक्ष्य:-

ऊपर दिए गए लक्ष्यों और आइडिया को इन तरीकों से लागू किया जा सकता है:-

मौजूदा Jekyll थीम को बेहतर और मज़बूत थीम पर स्विच करना. जेकिल की थीम को फिर से इस्तेमाल करने की वजह यह है कि इसमें रखरखाव करने वाले लोग आसानी से प्रोजेक्ट के वर्कफ़्लो को समझ पाएंगे और अपना योगदान दे पाएंगे. इसकी वजह यह है कि उन्हें जेकिल की नई थीम से मिलते-जुलते मौजूदा फ़्रेमवर्क और थीम के बारे में पहले से पता है.

इंटरनेट पर अलग-अलग Jekyll थीम देखने के बाद मुझे पता चला कि gRPC-Gateway दस्तावेज़ साइट के लिए यह https://id विवरणbewriting.com/documentation-theme-jekyll/ थीम सुइट सबसे अच्छा है, क्योंकि यह नीचे दी गई सुविधा है:

• मार्कडाउन:- इससे तकनीकी लेखकों को इंस्टॉलेशन की चिंता नहीं करनी पड़ती. वे .md फ़ाइल में आसानी से लिख सकते हैं. वेबसाइट पर मौजूद बदलाव करें बटन (नई सुविधा) पर क्लिक करके, कोई भी व्यक्ति इस पेज को बेहतर बनाने के लिए योगदान दे सकता है. इसके लिए, GitHub में पेज में बदलाव किया जा सकता है या बदलाव का सुझाव दिया जा सकता है. इससे उपयोगकर्ताओं को नया कॉन्टेंट जोड़ने या कॉन्टेंट को बेहतर बनाने के लिए उसमें बदलाव करने में दिलचस्पी होगी.

• दस्तावेज़ खोजने के लिए:- उपयोगकर्ता के पास खोज बॉक्स होना चाहिए, ताकि वह आसानी से और तुरंत काम के कॉन्टेंट को खोज सके.

• टिप्पणियों का सेक्शन:- उपयोगकर्ता के पास पोस्ट और ट्यूटोरियल पर टिप्पणी करने और अपने विचार शेयर करने का विकल्प हो सकता है. वे प्रोजेक्ट के दस्तावेज़ पर, दूसरे लोगों के विचार पढ़ सकते हैं.

• नए रिलीज़ नोट और ब्लॉग:- वेबसाइट को नए ब्लॉग पोस्ट और मौजूदा डेवलपमेंट और रोडमैप से जुड़ी खबरों से अपडेट किया जाना चाहिए. इसलिए, लैंडिंग पेज पर इस तरह की ब्लॉगिंग मौजूद होनी चाहिए.

• तेज़ी से डेवलपमेंट:- एसएसजी (स्टैटिक साइट जनरेटर) फ़्रेमवर्क में से ज़्यादातर सर्वर में चल रहे हैं. साथ ही, फ़ाइल में किए गए बदलाव यूज़र इंटरफ़ेस (यूआई) में तुरंत दिखते हैं. साथ ही, डिप्लॉय और बिल्ड करने की प्रोसेस भी आसान होनी चाहिए. आने वाले समय में, अगर हमें फ़्रेमवर्क बदलना है, तो हम इसका इस्तेमाल करेंगे. इसके बाद, यह आसान हो जाएगा. ज़्यादातर फ़्रेमवर्क, मार्कडाउन भाषा में लिखने की सुविधा देते हैं. इसलिए, .md फ़ाइलों को सिर्फ़ एक जगह से दूसरी जगह ले जाने और कुछ बदलाव करने से ही काम हो जाएगा.

यहां मौजूदा वेबसाइट के पेजों को नई वेबसाइट के सेक्शन और पेजों में बांटा जा रहा है :

• लैंडिंग पेज:-

लैंडिंग पेज पर gRPC-Gateway की मुख्य सुविधाओं के बारे में बताया जाना चाहिए.

• gRPC-Gateway का इस्तेमाल शुरू करना (उपयोगकर्ता गाइड पर रीडायरेक्ट करता है)
• इंस्टॉल करने के आसान निर्देश (कम शब्दों में निर्देश)
• gRPC-गेटवे का इस्तेमाल क्यों करें
• gRPC-Gateway का इस्तेमाल करने वाला प्रोजेक्ट

इसलिए, ज़्यादा जानकारी देने के बजाय, लैंडिंग पेज पर मुख्य बातें दिखाएं और ज़्यादा जानकारी के लिए लिंक दें.

• gRPC-Gateway के लिए उपयोगकर्ता गाइड वाला पेज:-

• इंस्टॉल करने का तरीका बताने वाली गाइड.
• gRPC-गेटवे के साथ क्विक स्टार्ट करें.

• gRPC-Gateway डेवलपर गाइड पेज:-

डेवलपमेंट गाइड, योगदान देने से जुड़ी गाइड, Git सेटअप, आचार संहिता, दस्तावेज़ सेटअप, डेवलपमेंट वर्कफ़्लो वगैरह, अंदर मौजूद मिलते-जुलते पेजों पर ले जाते हैं. इसलिए, सभी फ़ाइलों को रीफ़ैक्टर और फिर से व्यवस्थित करने की ज़रूरत है. मुख्य डेवलपमेंट पेज में ये सभी पेज होने चाहिए. साथ ही, हर चरण में हाइपरलिंक बनाया जाएगा.

• gRPC-Gateway पेज के बारे में जानकारी:-

योगदान देने वाले सभी लोगों की सूची टीम सेक्शन में मौजूद होनी चाहिए क्विक लिंक और प्रॉडक्ट की जानकारी वाला दस्तावेज़. इसमें नए ब्लॉग जोड़े जाएंगे, ताकि उपयोगकर्ता मौजूदा gRPC-गेटवे की खबरों के बारे में पढ़ सकें.

• ब्लॉग, रिलीज़ नोट, और ट्यूटोरियल पेज:-

मुझे लगता है कि वेबसाइट में ब्लॉगिंग का विकल्प होना चाहिए. इससे खबरें और रिलीज़ आसानी से शेयर की जा सकती हैं. इस ट्यूटोरियल पेज पर, gRPC-Gateway एपीआई और कॉन्सेप्ट को समझने के लिए कुछ लोकप्रिय बातचीत और लेख दिए गए हैं. योगदान देने वाले लोग, ट्यूटोरियल पेज पर अपने ट्यूटोरियल के लिंक जोड़ सकते हैं.

ऊपर दिए गए टास्क को पूरा करने के बाद, उन बदलावों को v2 ब्रांच में अपडेट करें और gRPC-गेटवे की मास्टर ब्रांच के साथ भी बदलाव करें.

इस प्रोजेक्ट का दूसरा लक्ष्य:-

gRPC-Gateway दस्तावेज़ को ज़्यादा बेहतर और पढ़ने लायक बनाने के लिए, अन्य बदलाव करने होंगे:-

• व्याकरण और टाइपिंग से जुड़ी गड़बड़ियों को ठीक करना. साथ ही, gRPC-Gateway की सभी मौजूदा फ़ाइलों में, साइट के लिंक और पोस्ट को व्यवस्थित और अलाइन करना.

• ज़रूरत पड़ने पर, gRPC-Gateway में ज़्यादा दस्तावेज़ और कॉन्टेंट जोड़ना. ऐसा इसलिए, क्योंकि ज़्यादातर सुविधाओं के लिए बहुत कम दस्तावेज़ उपलब्ध हैं. जैसे, AWS, बैकग्राउंड, और इस्तेमाल वगैरह के बारे में साइट के दस्तावेज़ सेक्शन में.

• Gofmt फ़ॉर्मैट के मुताबिक, Go स्निपेट gRPC-Gateway को फिर से तैयार करना

ऊपर दिए गए टास्क को पूरा करने के बाद, v2 शाखा में भी वही बदलाव करें. साथ ही, gRPC-Gateway की मास्टर शाखा में भी बदलाव करें.

इस प्रोजेक्ट के लिए मैं सही व्यक्ति क्यों हूं:

मुझे लगता है कि मैं इस प्रोजेक्ट के लिए सही व्यक्ति हूं, क्योंकि:-

• मेरे पास संगठनों के दस्तावेज़ों को बेहतर बनाने का अनुभव है. साथ ही, मैं किसी भी वर्शन कंट्रोल सिस्टम का इस्तेमाल कर सकता/सकती हूं. इसलिए, GitHub पर निर्देशों को पूरा करने में कोई समस्या नहीं होगी. • इसके अलावा, मुझे ऐसे प्रोजेक्ट पर काम करना अच्छा लगता है जिनसे लोगों को फ़ायदा मिलता है. मेरा मानना है कि अगर आपको किसी को किसी काम को सबसे बेहतर तरीके से करने के लिए कहना है, तो आपको उसका दस्तावेज़ बनाना चाहिए. अपनी प्रोसेस का रिकॉर्ड रखने से, यह पक्का किया जा सकता है कि सभी काम सही तरीके से पूरे हो सकें और सभी काम एक जैसे तरीके से काम कर सकें. • मुझे gRPC-गेटवे के वर्कफ़्लो और कोड बेस के बारे में जानकारी है, क्योंकि मैंने पिछले दो महीने से gRPC-गेटवे में योगदान दिया है और 11 पीआर मर्ज किए हैं.