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

इस पेज पर Google Docs के सीज़न के लिए स्वीकार किए गए एक तकनीकी लेखन प्रोजेक्ट की जानकारी है.

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

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

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

तकनीकी लेखक:

अरामराज

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

gRPC-Gateway की मौजूदा Docs साइट को रीफ़ैक्टर करना

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

मानक अवधि (तीन महीने)

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

असर:

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

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

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

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

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

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

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

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

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

संभावित लक्ष्यों और आइडिया की संरचना और रोडमैप:

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

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

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

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

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

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

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

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

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

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

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

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

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

इसलिए, लंबा ब्यौरा लिखने के बजाय, लैंडिंग पेज पर मुख्य बातों को दिखाएं. साथ ही, जानकारी देने के लिए लिंक भी दें.

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

• इंस्टॉल करने का तरीका बताने वाली गाइड.
• gRPC-Gateway से तुरंत शुरू करें.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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