OpenMRS प्रोजेक्ट

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

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

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

OpenMRS

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

Saurabh

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

REST API के लिए, उपयोगकर्ता के हिसाब से बनाए गए GitHub दस्तावेज़ को बड़ा करना

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

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

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

मुख्य लक्ष्य

एपीआई के इस्तेमाल के बारे में दिशा-निर्देश जोड़ने के लिए, OpenMRS स्वैगर पर आधारित REST API दस्तावेज़ को बेहतर बनाएं.

प्रोजेक्ट का ब्यौरा

OpenMRS REST API, डेवलपर के लिए OpenMRS से डेटा ऐक्सेस करने के मुख्य तरीकों में से एक है. OpenMRS वेब सेवाओं के एपीआई के लिए, Swagger पर आधारित अपने-आप जनरेट होने वाला दस्तावेज़ पहले से मौजूद है. साथ ही, GitHub पर आधारित स्टैटिक दस्तावेज़ भी मौजूद है. इस सीज़न ऑफ़ दस्तावेज़ में, हम GitHub पर आधारित उस दस्तावेज़ को बढ़ाने वाले हैं.

खास जानकारी

बर्क के सुझाव के मुताबिक, OpenMRS Talk के बारे में थोड़ी रिसर्च करने के बाद, मुझे पता चला कि यह प्रोजेक्ट 2017 में GSOC प्रोजेक्ट के तौर पर शुरू हुआ था. गायन वीरकुट्टी का मुख्य मकसद, OpenMRS REST API के मौजूदा दस्तावेज़ को बेहतर बनाना था, ताकि स्वैगर के स्पेसिफ़िकेशन को बेहतर बनाया जा सके. साथ ही, स्वैगर के डेटा को जनरेट करने के तरीके में भी सुधार किया जा सके. इससे, स्वैगर के दस्तावेज़ का बेहतर वर्शन जनरेट हो सकेगा. प्रोजेक्ट में हासिल की गई सभी ज़रूरी जानकारी, इस OpenMRS टॉक पोस्ट में यहां बताई गई है और यह काफ़ी काम की थी.

इसके बाद, साल 2019 में इस प्रोजेक्ट में नया बदलाव किया गया. इसके बाद, हमने स्वैगर के दस्तावेज़ों में हुए छोटे-मोटे बदलाव करके, इस प्रोजेक्ट को अलग-अलग तरह से पेश किया. इसके बजाय, हमने GitHub के हिसाब से स्टैटिक दस्तावेज़ तैयार किया है. हम इस सीज़न में Docs में भी इस सुविधा को उपलब्ध कराएंगे.

इसलिए, मौजूदा प्रोजेक्ट के प्रस्ताव के बारे में खास जानकारी यह है :

1. कुछ लोकप्रिय भाषाओं (खास तौर पर java और javascript) में उदाहरण दिए जा रहे हैं.
2. स्लेट दस्तावेज़ के लिए, प्लेग्राउंड की सुविधा जोड़ी गई है. यह सुविधा, Swagger की ""आज़माएं"" सुविधा जैसी ही है.
3. अब तक किए गए काम को बेहतर बनाना और उसमें बदलाव करना.
4. जो संसाधन मौजूद नहीं हैं उन्हें ढूंढना और जोड़ना.
5. दस्तावेज़ों के कंसोल सेक्शन में थोड़ी और जानकारी जोड़ना

पूरी जानकारी

1. अलग-अलग भाषाओं में उदाहरण दें.

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

1. एपीआई के उदाहरणों की जांच करने के लिए, Playground की सुविधा जोड़ी जा रही है

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

1. अब तक किए गए काम को फिर से तैयार करना और उसमें सुधार करना

कर्ल के मौजूदा उदाहरणों की जांच की जा रही है

इस सेक्शन पर इस साल इस प्रोजेक्ट में सबसे ज़्यादा ध्यान दिया जा रहा है. फ़िलहाल, GitHub API के दस्तावेज़ों में सिर्फ़ curl के उदाहरण मौजूद हैं. इनमें से कुछ को सीधे ब्राउज़र से देखने के लिए, डेमो सर्वर पर सीधे तौर पर नहीं चलाया जा सकता. हम सभी मौजूदा एंडपॉइंट की जांच करेंगे और उन सभी curl अनुरोधों के जवाबों के साथ एक आसान दस्तावेज़ बनाए रखेंगे जो हमें उन curl अनुरोधों को चलाने पर मिलते हैं. अगर ज़रूरी हो, तो इस काम को पूरा करने के लिए, मैं Postman का इस्तेमाल करूंगा. साथ ही, मैं swagger दस्तावेज़ में पहले से मौजूद 'आज़माएं' सुविधा का भी इस्तेमाल करूंगा.

कुछ उदाहरणों में एपीआई के रिस्पॉन्स मौजूद नहीं हैं

मौजूदा curl के उदाहरणों के लिए कुछ जवाब जोड़े गए हैं, लेकिन कुछ curl के उदाहरणों में जवाब नहीं हैं. मुझे लगता है कि भले ही रिस्पॉन्स में ज़्यादा जानकारी न हो, जो आम तौर पर रिसॉर्स को खाली करने जैसे ऑपरेशन के मामले में होता है, लेकिन हमारे पास JSON API रिस्पॉन्स का उदाहरण होना चाहिए. हालांकि, हमने सभी संभावित रिस्पॉन्स कोड और उन्हें पाने की वजह के बारे में दस्तावेज़ में जानकारी दी है. मुझे लगता है कि इससे एपीआई दस्तावेज़ में मौजूद उदाहरणों को ज़्यादा एक जैसा बनाया जा सकेगा !!

अलग-अलग ऑपरेशन के काम करने वाले उदाहरण मौजूद नहीं हैं

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

जैसा कि बर्क ने अपनी पोस्ट में कई बार बताया है कि अच्छे यूज़र इंटरफ़ेस (यूआई) और शानदार इंटरफ़ेस के बजाय दस्तावेज़ में सादगी और जानकारी देने को प्राथमिकता दी जाती है. मैं इन सिद्धांतों का पालन करता हूं और OpenMRS Webservices API पर काम करने वाले डेवलपर से बात करके पिछले एंडपॉइंट को ज़्यादा से ज़्यादा जानकारी देने की कोशिश करता/करती हूं. मैं प्राथमिकता के हिसाब से काम करूंगा. साथ ही, अपने मेंटर से बात करके यह तय करूंगा कि दस्तावेज़ों में कौनसी चीज़ें जोड़ी जानी चाहिए और उन्हें पहले पूरा करना ज़रूरी है.

इस्तेमाल के उदाहरणों को साफ़ तौर पर हेडलाइन के तौर पर जोड़ना

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

1. ऐसे संसाधनों को ढूंढना और उनका दस्तावेज़ बनाना जो मौजूद नहीं हैं

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

निष्कर्ष

मैं OpenMRS कम्यूनिटी का कुछ समय से हिस्सा हूं. मैं Android Client प्रोजेक्ट में लगातार योगदान देता/देती हूं. जहां सर्वर से इंटरैक्ट करने के लिए, मैं अक्सर एपीआई के साथ इंटरैक्ट करता/करती हूं. इसलिए, मुझे लगता है कि एपीआई दस्तावेज़ों को बेहतर बनाने के इस प्रोजेक्ट पर काम करना मेरे लिए आसान होगा. ऐसा इसलिए, क्योंकि मैं खुद एक डेवलपर हूं और यह देख सकता हूं कि मेरे काम से दूसरे डेवलपर का काम आसान हो रहा है या नहीं. मुझे यहां होस्ट किए गए, उपयोगकर्ता के हिसाब से बनाए गए दस्तावेज़ों के रिपॉज़िटरी के लिए इस्तेमाल किए जाने वाले टूल के बारे में पता है. मैंने इस रिपॉज़िटरी और टूल, जैसे कि slateUI के बारे में जानने के लिए, इस रिपॉज़िटरी में कई योगदान दिए हैं. एपीआई को उसके दस्तावेज़ों के हिसाब से ही अच्छा माना जाता है. इसलिए, मुझे OpenMRS Rest API के दस्तावेज़ों को बेहतर बनाकर, उन्हें थोड़ा बेहतर बनाना है.

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