Linux फ़ाउंडेशन प्रोजेक्ट

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

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

ओपन सोर्स संगठन:
The Linux Foundation
टेक्निकल राइटर:
बोरॉन
प्रोजेक्ट का नाम:
दस्तावेज़ होस्ट करने और जनरेट करने की प्रोसेस को बेहतर बनाएं. साथ ही, 'शुरू करें' पेजों और डेवलपर गाइड को फिर से व्यवस्थित करें.
प्रोजेक्ट की अवधि:
स्टैंडर्ड अवधि (तीन महीने)

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

ऐब्स्ट्रैक्ट :

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

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

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

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

  • AGL की दस्तावेज़ वेबसाइट, अलग-अलग रिपॉज़िटरी से फ़ेच की गई मार्कडाउन फ़ाइलों के कलेक्शन पर आधारित है.
  • फ़िलहाल, दस्तावेज़ वाले पेज अलग-अलग सोर्स में मार्कडाउन के तौर पर होस्ट किए जाते हैं. इसके लिए, cordova प्रोजेक्ट के इंजन का इस्तेमाल किया जाता है.
  • इससे, दस्तावेज़ बनाने और होस्ट करने की प्रोसेस के लिए चार रिपॉज़िटरी सेटअप हो जाती हैं :
  • Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : इसमें Jekyll वेबसाइट का टेंप्लेट होता है.
  • Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : इसमें ऐसे टूल शामिल हैं जो Markdown फ़ाइलों से तकनीकी वेबसाइट को अपने-आप जनरेट करते हैं.
  • Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : सामान्य दस्तावेज़ों और गाइड के लिए सोर्स (मार्कडाउन [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]).
  • Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : दस्तावेज़ की साइट [https://gist.github.com/growupboron/docs.automotivelinux.org] के लिए, GitHub पेजों की रिपॉज़िटरी डिप्लॉय की गई.
  • docs-tools [https://github.com/automotive-grade-linux/docs-tools] में उपलब्ध एक टूल (स्क्रिप्ट), docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] में मौजूद fetched_files.yml के मुताबिक, सभी मार्कडाउन फ़ाइलों को इकट्ठा करने और टेंप्लेट बनाने का काम करता है.
  • agl documentation वेबसाइट जनरेट करने का मौजूदा वर्कफ़्लो : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
  • section_version.yml में, सभी बुक वाईएएमएल फ़ाइलों के लिंक होते हैं. यह docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] से सभी बुक वाईएएमएल फ़ाइलों को फ़ेच करता है. बुक की YAML फ़ाइलों में, रिमोट रिपॉज़िटरी से आपकी मार्कडाउन फ़ाइलों के सभी यूआरएल होते हैं.
  • सभी मार्कडाउन फ़ाइलें फ़ेच होने के बाद, टूल प्रोसेस करके docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] में AGL doc वेबसाइट जनरेट करते हैं. इसके बाद, इसे डिप्लॉय किया जाता है.
  • पाइपलाइन को बनाए रखने की मौजूदा प्रोसेस, उपयोगकर्ता और डेवलपर के लिए आसान नहीं है. खास तौर पर, नए योगदानकर्ताओं के लिए. बिल्ड करने और होस्ट करने की इस वर्कफ़्लो पाइपलाइन को डेवलपर के लिए ज़्यादा आसान और बेहतर बनाया जा सकता है. इससे डेवलपर, दस्तावेज़ जनरेट करने और डिप्लॉयमेंट वर्कफ़्लो को बनाए रखने के बजाय, दस्तावेज़ के हिस्से पर फ़ोकस कर पाएंगे.