Rails प्रोजेक्ट्स के लिए एक कुशल डॉक्यूमेंटेशन वर्कफ़्लो डिज़ाइन करना

आधुनिक डॉक्यूमेंटेशन वर्कफ़्लोज़ सॉफ्टवेयर डेवलपमेंट वर्कफ़्लो के साथ तेजी से जुड़ रहे हैं। आप GitHub या Jira में डॉक्यूमेंटेशन इश्यूज़ ट्रैक कर सकते हैं, या आप कोड कमेंट्स या Markdown फाइलों में डॉक्स लिख सकते हैं। आपकी टीम के डेवलपर्स टेक्निकल राइटर्स के साथ सीधे काम कर सकते हैं, या वे स्वतंत्र रूप से डॉक्स लिख सकते हैं। डॉक्स अक्सर कोड रिपॉजिटरीज़ में स्टोर किए जाते हैं, लिंटर्स का उपयोग करके गुणवत्ता के लिए टेस्ट किए जाते हैं, और स्टैटिक साइट्स पर लगातार प्रकाशित किए जाते हैं। टेक्निकल राइटर्स ने हाल ही में इस प्रकार के वर्कफ़्लो का वर्णन करने के लिए docs-like-code या docs-as-code शब्द गढ़ा है।

Docs-as-code ऑटोमेशन द्वारा परिभाषित है। इसमें परिचित डेवलपमेंट टूल्स का उपयोग करके डॉक्यूमेंटेशन बनाना, अपडेट करना, समीक्षा करना और अनुमोदित करना शामिल है:

• इश्यू ट्रैकर्स
• वर्जन कंट्रोल टूल्स
• प्लेन-टेक्स्ट फाइलें
• टेक्स्ट और कोड एडिटर्स
• स्टैटिक साइट जनरेटर्स
• निरंतर प्रकाशन

डॉक्स को संबंधित कोड के समान रिपॉजिटरीज़ में स्टोर किया जा सकता है, जिससे यह सुनिश्चित करना आसान हो जाता है कि डॉक्स कोड के साथ-साथ अपडेट किए जाते हैं।

यह वर्कफ़्लो लचीला है और टूल्स और मेथडोलॉजीज़ के कई संयोजनों के अनुकूल है। उदाहरण के उद्देश्यों के लिए, यह ट्यूटोरियल Jekyll जैसे रूबी-आधारित टूल्स का उपयोग करके एक Rails ऐप के लिए docs-as-code वर्कफ़्लो विकसित करता है। डॉक्स GitHub में ऐप के साथ स्टोर किए जाते हैं और GitHub इश्यूज़, लेबल्स, प्रोजेक्ट्स, और पुल रिक्वेस्ट समीक्षाओं का उपयोग करके प्रबंधित किए जाते हैं। यह उदाहरण docs-as-code सिद्धांतों को दर्शाता है जिन्हें अन्य टूल्स के लिए अनुकूलित किया जा सकता है और अन्य वर्कफ़्लोज़ में एकीकृत किया जा सकता है।

पूर्वापेक्षाएँ

यह गाइड डेवलपर्स के लिए है। आपको निम्नलिखित टूल्स से परिचित होना चाहिए: Git, कोड एडिटर्स, और Markdown। यह लेख बताता है कि इन टूल्स का उपयोग डॉक्यूमेंटेशन वर्कफ़्लो बनाने के लिए कैसे किया जाए।

इस लेख के साथ एक लाइव सैंपल साइट है, जिसे Netlify द्वारा होस्ट किया गया है, और एक सैंपल GitHub रिपॉजिटरी।

इस लेख के साथ चलने के लिए, कुछ कमांड्स के साथ Rails में एक साधारण ब्लॉग एप्लिकेशन बनाएं:

gem install rails rails new blog cd blog rails generate scaffold Post title:string body:text 

config/routes.rb में, एक इंडेक्स पेज बनाएं:

Rails.application.routes.draw do resources :posts root 'posts#index' end 

अंत में, डेटाबेस माइग्रेशन चलाएं और यह जांचने के लिए Rails सर्वर शुरू करें कि सब कुछ काम करता है:

rails db:migrate rails s 

localhost:3000 पर जाएं। आपको पोस्ट्स की एक खाली सूची और एक नया पोस्ट बनाने का लिंक दिखाई देना चाहिए।

कंटेंट स्ट्रेटेजी बनाना

योजना डॉक्यूमेंटेशन वर्कफ़्लो विकसित करने में पहला कदम है, जैसे यह सॉफ्टवेयर के साथ है। आपके डॉक्स की योजना में एक कंटेंट स्ट्रेटेजी शामिल होनी चाहिए, जो निर्धारित करती है कि किन विषयों को प्रलेखित करने की आवश्यकता है और कैसे।

कंटेंट स्ट्रेटेजी विकसित करना शुरू करने के लिए, निम्नलिखित प्रश्नों का उत्तर दें:

• आपके इच्छित दर्शक कौन हैं?
  • क्या वे डेवलपर्स, कम तकनीकी उपयोगकर्ता, या दोनों हैं?
  • क्या उन्हें आपके कोड या डॉक्स में योगदान करने की अनुमति है?
  • क्या वे आपकी कंपनी के आंतरिक या बाहरी हैं या दोनों?
• उपयोगकर्ता क्या हासिल करने की कोशिश कर रहे हैं?
• उपयोगकर्ता आपके डॉक्स से परामर्श करके किन समस्याओं को हल करने की कोशिश कर रहे हैं?
• उपयोगकर्ता आपके डॉक्स से कैसे परामर्श करेंगे?
  • क्या एक साधारण README पर्याप्त होगा?
  • क्या उपयोगकर्ताओं को डॉक्यूमेंटेशन तक पहुंचने के लिए विशेष अनुमति की आवश्यकता होगी?

उदाहरण के लिए, कल्पना करें कि आपके पास एक साथ API वाला Rails ऐप है। ग्राहकों के लिए, आप अपने सभी UI फीचर्स के लिए एक सार्वजनिक यूज़र गाइड विकसित करना चाह सकते हैं। एक यूज़र स्टोरी हो सकती है, "एक उपयोगकर्ता के रूप में, मैं एक ब्लॉग पोस्ट बनाना चाहता हूं।"

आप डेवलपर्स के लिए रेफरेंस डॉक्यूमेंटेशन भी बना सकते हैं। एक डेवलपर स्टोरी हो सकती है, "एक डेवलपर के रूप में, मैं किसी विशिष्ट उपयोगकर्ता के सभी ब्लॉग पोस्ट्स को पुनः प्राप्त करना चाहता हूं।"

आप Jekyll या WordPress जैसे स्टैटिक साइट जनरेटर का उपयोग करके यूज़र डॉक्स को ब्रांडेड, उपयोगकर्ता-अनुकूल वातावरण में प्रस्तुत कर सकते हैं। आपके आंतरिक डेवलपर्स के लिए, एक साधारण YARD-जनरेटेड साइट पर्याप्त हो सकती है। यह ट्यूटोरियल आपको दोनों प्रकार के डॉक्यूमेंटेशन साइट्स के उदाहरण दिखाएगा।

डॉक्यूमेंटेशन को आपके वर्तमान वर्कफ़्लो में भी एकीकृत किया जा सकता है। उदाहरण के लिए, यदि आपकी टीम 2-सप्ताह के स्प्रिंट्स में कोड लिखती है, तो अपने डॉक्यूमेंटेशन को उसी शेड्यूल पर प्रबंधित करने पर विचार करें।

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

फीडबैक इकट्ठा करना कंटेंट स्ट्रेटेजी का एक महत्वपूर्ण हिस्सा है। हर डॉक पेज पर उपयोगकर्ताओं के लिए फीडबैक के साथ आपसे संपर्क करने या GitHub के माध्यम से डॉक्स में योगदान करने का एक तरीका जोड़ने पर विचार करें। एक फीडबैक बटन आमतौर पर सिर्फ एक फॉर्म होता है जो कंपनी ईमेल पते पर जाता है; इस कार्य को सौंपे गए व्यक्ति(यों) तब प्रत्येक फीडबैक आइटम को ले सकते हैं और इसे समीक्षा और कार्यान्वयन के लिए Jira या GitHub इश्यू में बदल सकते हैं।

एक सुसंगत शैली और सटीक शब्दावली के उपयोग को सुनिश्चित करने के लिए, एक कंपनी स्टाइल गाइड बनाएं या किसी मौजूदा का पालन करें। यहां कुछ डॉक्यूमेंटेशन स्टाइल गाइड्स के उदाहरण दिए गए हैं जो अधिकांश सॉफ्टवेयर प्रोजेक्ट्स के लिए काम करेंगे:

• Google डेवलपर डॉक्यूमेंटेशन स्टाइल गाइड
• GitLab डॉक्यूमेंटेशन स्टाइल गाइड
• Microsoft राइटिंग स्टाइल गाइड

कंटेंट स्ट्रेटेजी पर आगे पढ़ने के लिए यहां कुछ लिंक्स दिए गए हैं जो आपको शुरू करने में मदद करेंगे:

• डेवलपर पोर्टल्स के साथ DX कंटेंट स्ट्रेटेजी
• डॉक्यूमेंटेशन कंटेंट स्ट्रेटेजी पर प्राइमर

डॉक्स साइट बनाना

अपनी कंटेंट स्ट्रेटेजी से, आप यह निर्धारित कर सकते हैं कि आपके डॉक्स को इच्छित दर्शकों के सामने कैसे प्रस्तुत किया जाएगा। यह निर्धारित करना कि कौन आपके डॉक्स लिखेगा, इस निर्णय को सूचित करने में भी मदद करेगा। उदाहरण के लिए, यदि डेवलपर्स और योगदानकर्ता कोड कमेंट्स में डॉक्यूमेंटेशन लिखेंगे, तो RDoc या YARD का उपयोग इन कमेंट्स से एक साधारण स्टैटिक डॉक्स साइट बनाने के लिए किया जा सकता है। यदि यूज़र डॉक्यूमेंटेशन Markdown फाइलों में लिखा जाएगा, तो Jekyll जैसे स्टैटिक साइट जनरेटर आपके डॉक्स को प्रकाशित करने के लिए बेहतर विकल्प होगा। बेशक, आप एक साइट को स्क्रैच से भी बना सकते हैं जो आपकी टीम और आपके प्रोजेक्ट के लिए काम करे।

यह लेख Jekyll और YARD दोनों का उपयोग करके Rails ऐप के लिए दोनों प्रकार की डॉक्यूमेंटेशन साइट्स को दर्शाता है। ध्यान दें कि Jekyll रूबी-आधारित है और Rails ऐप में अच्छी तरह से एकीकृत होता है।

Jekyll

Jekyll का उद्देश्य प्लेन टेक्स्ट को स्टैटिक वेबसाइट में बदलना है। Jekyll एक _site फोल्डर बनाता है जिसमें स्टैटिक साइट फाइलें होती हैं जिन्हें किसी भी होस्टिंग सेवा द्वारा प्रकाशित किया जा सकता है। इन फाइलों को GitHub पर पुश करने का अर्थ है कि आप अपने डॉक्स को प्रकाशित करने के लिए Netlify जैसे निरंतर प्रकाशन टूल्स का उपयोग कर सकते हैं।

Jekyll के साथ सबसे सरल वर्कफ़्लो में Markdown फाइलों में डॉक्स लिखना और उन्हें GitHub पर पुश करना शामिल है। यदि आप Netlify का उपयोग करते हैं, तो जब आप इन परिवर्तनों को रिपॉजिटरी में मर्ज करते हैं तो यह स्वचालित रूप से साइट को डिप्लॉय करता है। इस प्रक्रिया का अगले खंड में अधिक विस्तार से वर्णन किया गया है।

Jekyll साइट बनाने के लिए, अपने Rails ऐप के रूट डायरेक्टरी (जैसे /blog) से Jekyll और Bundler इंस्टॉल करें:

gem install jekyll bundler 

Jekyll साइट बनाने और इसे लोकल डेवलपमेंट सर्वर से चलाने के लिए केवल तीन कमांड्स की आवश्यकता होती है:

jekyll new docs cd docs bundle exec jekyll serve 

यह एक /docs डायरेक्टरी बनाता है जिसमें एक न्यूनतम Jekyll साइट होती है (डिफ़ॉल्ट Minima नामक एक ब्लॉग थीम है)। आप इसे अपने कस्टम Jekyll डॉक्स साइट के लिए बेस के रूप में उपयोग कर सकते हैं। वैकल्पिक रूप से, आप just-the-docs जैसी डॉक्स थीम इंस्टॉल कर सकते हैं, जो साइडबार नेविगेशन और साइट सर्च कार्यक्षमता के साथ आती है।

यह ट्यूटोरियल just-the-docs थीम का उपयोग करेगा। इसे इंस्टॉल करने के लिए, /docs डायरेक्टरी से निम्न चलाएं:

bundle add just-the-docs 

Gemfile से minima थीम को हटा दें क्योंकि यह डिफ़ॉल्ट थीम है जिसका आप अब उपयोग नहीं करेंगे। आप posts डायरेक्टरी को भी हटा सकते हैं।

इसके बाद, इस थीम को Jekyll के _config.yml फाइल में जोड़ें। जब आप यहां हैं तो आप अपनी साइट का शीर्षक और विवरण भी कस्टमाइज़ कर सकते हैं:

title: Docs Site email: your-email@example.com description: >- एक Rails ऐप के लिए Jekyll डॉक्स साइट। baseurl: "" # आपकी साइट का उपपथ, जैसे /blog url: "" # आपकी साइट के लिए बेस होस्टनाम और प्रोटोकॉल, जैसे https://example.com twitter_username: "" github_username: "" # बिल्ड सेटिंग्स theme: just-the-docs 

सर्वर को फिर से शुरू करें, और आपको एक ज्यादातर खाली डॉक्स साइट दिखाई देगी:

अपने Jekyll थीम के दस्तावेज़ीकरण की जांच करें कि कौन सी डायरेक्टरी आपकी Markdown फाइलों को रखनी चाहिए। just-the-docs के लिए, Markdown फाइलें रूट डायरेक्टरी में रह सकती हैं, जो आपकी साइट के बेस पथ से मेल खाती है। यह देखने के लिए रूट डायरेक्टरी में एक नई Markdown फाइल बनाएं कि यह कैसे काम करता है:

--- layout: default title: Sample Doc nav_order: 1 --- # Models {: .no_toc } ## Table of contents {: .no_toc .text-delta } 1. TOC {:toc} --- ## Markdown header Write **Markdown** here! 

अपने नए सैंपल डॉक को देखने के लिए सर्वर को फिर से शुरू करें:

अब आपके Rails ऐप डायरेक्टरी में /docs फोल्डर में एक बुनियादी Jekyll साइट है! Jekyll थीम को कस्टमाइज़ करने या अपना खुद का लिखने में मदद के लिए Jekyll डॉक्स देखें।

YARD

Rdoc और YARD जैसे डॉक्यूमेंटेशन जनरेटर्स कोड कमेंट्स से डेवलपर डॉक्यूमेंटेशन जनरेट करते हैं। आप YARD का उपयोग करके एक स्टैंडअलोन डॉक्स साइट बना सकते हैं, जो Rdoc और अन्य सिंटैक्स को स्वीकार करता है। इस उदाहरण में, हम अपने मौजूदा Jekyll साइट में YARD डॉक्यूमेंटेशन जोड़ेंगे। Jekyll YARD द्वारा जनरेट की गई स्टैटिक फाइलों को /dev जैसे पथ पर प्रकाशित कर सकता है। आप अपनी डॉक्यूमेंटेशन साइट बनाने के लिए YARD का उपयोग अकेले भी कर सकते हैं।

जब Rails एक ऐप जनरेट करता है, तो यह कुछ बुनियादी कोड कमेंट्स भी जनरेट करता है:

# app/controllers/posts_controller.rb class PostsController < ApplicationController before_action :set_post, only: %i[ show edit update destroy ] # GET /posts or /posts.json def index @posts = Post.all end # GET /posts/1 or /posts/1.json def show end # GET /posts/new def new @post = Post.new end # GET /posts/1/edit def edit end # कोड छोड़ा गया end 

यह देखने के लिए कि YARD इन कमेंट्स का उपयोग डॉक्स साइट बनाने के लिए कैसे करता है, अपने Rails ऐप के रूट डायरेक्टरी से yard doc या yardoc कमांड चलाएं:

yardoc --output-dir docs/dev app/**/*.rb 

यदि yardoc कमांड काम नहीं करता है, तो bundle install yard के साथ YARD जेम इंस्टॉल करें।

YARD अपने आउटपुट फाइलों को output-dir में रखेगा, जिसे ऊपर की कमांड में Jekyll डायरेक्टरी /docs/dev पर सेट किया गया है। Jekyll अब YARD की साइट फाइलों को /dev बेस पथ के साथ प्रकाशित कर सकता है।

RDoc या अन्य सिंटैक्स (YARD दस्तावेज़ीकरण देखें) का उपयोग करके अधिक जटिल डॉक्यूमेंटेशन बनाया जा सकता है, लेकिन हम यहां मौजूदा डॉक्यूमेंटेशन पर ही रहेंगे।

Jekyll सर्वर शुरू करें और अपना YARD-जनरेटेड डॉक्यूमेंटेशन देखने के लिए localhost:4000/dev पर जाएं:

इस बिंदु पर, मुख्य Jekyll साइट से इन डेवलपर डॉक्स पर नेविगेट करने का कोई तरीका नहीं है। Jekyll साइट से डेवलपर डॉक्स का लिंक जोड़ने के लिए, docs/_config.yml में निम्नलिखित जोड़ें:

# ऊपरी दाएं नेविगेशन के लिए सहायक लिंक्स aux_links: "Developer Documentation": - "/dev" 

यह Jekyll और YARD की चर्चा का समापन करता है। अब जब आपकी डॉक्स साइट सेट अप हो गई है, तो डेवलपर्स और राइटर्स बस Markdown फाइलों (या कोड कमेंट्स) में कंटेंट लिख सकते हैं और उन्हें GitHub पर पुश कर सकते हैं। अगला खंड बताता है कि निरंतर प्रकाशन के साथ इन डॉक्स को कैसे डिप्लॉय किया जाए।

Netlify के साथ निरंतर प्रकाशन और डिप्लॉयमेंट

निरंतर प्रकाशन डॉक्स साइट्स के लिए सुविधाजनक है क्योंकि लाइव साइट को स्वचालित रूप से अपडेट किया जा सकता है जब डॉक्स में परिवर्तनों को अनुमोदित किया जाता है और रिपॉजिटरी में मर्ज किया जाता है। यह ट्यूटोरियल इस उद्देश्य के लिए Netlify का उपयोग करता है, लेकिन अन्य टूल्स उपलब्ध हैं, जैसे GitHub Pages, GitLab Pages, और Firebase।

हम जो साइट बना रहे हैं वह Netlify द्वारा होस्ट की गई है: डॉक्स साइट।

अपनी डॉक्स साइट के लिए Netlify सेट अप करने के लिए, Netlify अकाउंट के लिए साइन अप करके शुरू करें और इसे अपने Rails ऐप वाले GitHub रिपॉजिटरी से कनेक्ट करें।

निम्नलिखित सेटिंग्स का उपयोग करें:

Repository github.com/your-username/your-rails-repo Base directory docs Build command jekyll build Publish directory docs/\_site Builds Active 

यदि Netlify साइट बनाते समय कुछ सेटिंग्स उपलब्ध नहीं हैं, तो अभी Deploy पर क्लिक करें। फिर आप इसे कैंसिल कर सकते हैं और Deploy settings पर वापस आ सकते हैं। बेस डायरेक्टरी को docs पर सेट करें ताकि यह सुनिश्चित हो सके कि Netlify आपके Rails ऐप के बजाय Jekyll डॉक्स साइट डिप्लॉय करता है।

जब Netlify आपकी Jekyll साइट को डिप्लॉय करना समाप्त कर ले, तो लाइव साइट पर जाएं ताकि यह सुनिश्चित हो सके कि सब कुछ सही दिखता है।

Netlify का उपयोग करने का एक लाभ यह है कि यह प्रत्येक पुल रिक्वेस्ट से सीधे एक लाइव प्रीव्यू लिंक प्रदान करता है:

फिर आप पुल रिक्वेस्ट को मर्ज करने और अपनी साइट के पुनः डिप्लॉय को ट्रिगर करने से पहले जांच सकते हैं कि आपके परिवर्तन सही ढंग से प्रकाशित होंगे। अगला खंड इस वर्कफ़्लो को अधिक विस्तार से कवर करता है।

GitHub में संपादकीय वर्कफ़्लो स्थापित करना

डॉक्यूमेंटेशन लिखने की रणनीति और इसे प्रकाशित करने के लिए एक साइट के साथ, आप डॉक्स लिखना शुरू करने और उन्हें अपने सॉफ्टवेयर वर्कफ़्लो में एकीकृत करने के लिए तैयार हैं।

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

यहां GitHub का उपयोग करने वाली टीम के लिए एक उदाहरण संपादकीय वर्कफ़्लो है:

1. [राइटर] GitHub इश्यू में नोट की गई डॉक्यूमेंटेशन फीचर रिक्वेस्ट या बग के अनुसार एक फाइल बनाएं या अपडेट करें।
2. [राइटर] परिवर्तन को GitHub ब्रांच पर पुश करें।
3. [राइटर] एक पुल रिक्वेस्ट खोलें।
4. [समीक्षक] परिवर्तनों की समीक्षा करें।
5. [समीक्षक/मेंटेनर] परिवर्तनों को रिपॉजिटरी में मर्ज करें, जिससे डॉक्स साइट का एक नया बिल्ड ट्रिगर होना चाहिए।

GitHub स्वचालित रूप से आपके कंटेंट के परिवर्तन इतिहास को प्रबंधित करता है, जो docs-as-code वर्कफ़्लो में भी महत्वपूर्ण है। आप देख सकते हैं कि क्या बदला गया, किसने बदला, कब बदला, साथ ही क्यों या कैसे बदला गया (यदि कमेंट्स, चर्चा, या संबंधित इश्यू में उल्लेख किया गया है)। यह आपकी टीम के सभी सदस्यों के लिए किसी भी समय एक ही स्थान पर संग्रहीत होता है।

इश्यूज़ और लेबल्स

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

डॉक्स इश्यूज़ को कोड इश्यूज़ से अलग करने के लिए, आप लेबल्स का उपयोग कर सकते हैं। यह इंगित करने के लिए एक documentation लेबल जोड़ें कि यह डॉक्स से संबंधित है। आप विशिष्ट डॉक्स इश्यूज़ के लिए लेबल भी बना सकते हैं, जैसे docs::feature या docs::fix।

आप अपने इश्यू टेम्पलेट्स में इश्यू शीर्षक या उपयुक्त लेबल्स के संबंध में निर्देश जोड़ सकते हैं, जैसे आप कोड-संबंधी इश्यूज़ के लिए करते हैं।

वर्कफ़्लो लेबल्स, जैसे docs::in progress और docs::in review, भी उपयोगी हैं। वे दर्शाते हैं कि वर्तमान में क्या काम किया जा रहा है।

अपनी डॉक्यूमेंटेशन प्रक्रिया को परिभाषित करते समय, यह निर्दिष्ट करना सुनिश्चित करें कि इन लेबल्स को बदलने के लिए कौन जिम्मेदार है और कब। उदाहरण के लिए, मसौदा लिखने वाला व्यक्ति लेबल को docs::in progress में बदल देगा जब वे मसौदा लिखना शुरू करेंगे। जब समीक्षक को मसौदा प्राप्त होगा, तो समीक्षक को इश्यू लेबल को docs::in review में बदलना चाहिए।

वर्कफ़्लो प्रबंधित करना

छोटी टीमों और प्रोजेक्ट्स के लिए, GitHub Projects का उपयोग करना आपके संपादकीय कंटेंट को सीधे GitHub से प्रबंधित करने का एक सुविधाजनक तरीका है। वे प्रोजेक्ट मैनेजमेंट बोर्ड्स के समान हैं, जैसे Trello में, लेकिन कॉलम्स को सीधे इश्यूज़ और पुल रिक्वेस्ट्स से जोड़ा जा सकता है।

उदाहरण के लिए, "Automated kanban with reviews" टेम्पलेट का उपयोग करें ताकि नए इश्यूज़ और पुल रिक्वेस्ट्स स्वचालित रूप से बोर्ड में जुड़ जाएं। जब कोई समीक्षक समीक्षा शुरू करता है या पुल रिक्वेस्ट को अनुमोदित करता है, तो इश्यू कार्ड अगले कॉलम में चला जाता है। यह आपको सक्रिय इश्यूज़ और वे संपादकीय प्रक्रिया में कहां हैं, इसका ट्रैक रखने देता है।

बड़े प्रोजेक्ट्स के लिए जिनमें केवल डॉक्स से अधिक शामिल हैं, ऑटोमेशन नियम सेट अप करने के लिए project-bot GitHub App का उपयोग करें। उदाहरण के लिए, एक विशिष्ट लेबल जोड़ना या एक विशिष्ट समीक्षक असाइन करना स्वचालित कार्ड मूवमेंट को ट्रिगर करेगा। वैकल्पिक रूप से, आप Jira जैसे टूल का उपयोग करके डॉक्यूमेंटेशन मैनेजमेंट को अपने बड़े प्रोजेक्ट मैनेजमेंट वर्कफ़्लो में एकीकृत कर सकते हैं।

GitHub प्रोजेक्ट में project-bot ऐप के प्रदर्शन के लिए सैंपल ऐप देखें।

डॉक्यूमेंटेशन बनाना

यह खंड डॉक्यूमेंटेशन निर्माण को अधिक विस्तार से बताता है, मसौदा तैयार करने से लेकर प्रकाशन तक।

डॉक्स लिखना और संशोधित करना

आपके संपादकीय वर्कफ़्लो में पहला कदम कुछ डॉक्स लिखना है। डॉक्यूमेंटेशन लिखने के टिप्स के लिए, Write the Docs से A Beginner's Guide to Writing Documentation देखें।

उदाहरण के लिए, अपने Rails ब्लॉग ऐप के बारे में एक लेख बनाने के लिए, अपने Jekyll docs डायरेक्टरी में blog-posts.md नामक एक नई Markdown फाइल बनाएं:

--- layout: default title: Blog Posts nav_order: 1 --- ## Creating a Blog Post ... 

जब आप कोड लिख रहे होते हैं, तो आप शायद सिंटैक्स हाइलाइटर्स और कोड लिंटर्स का उपयोग करके लिखते समय सिंटैक्स की जांच कर रहे होते हैं। यदि आप कोड एडिटर में अपने डॉक्स लिखते हैं, तो आप समान लिंटर्स का उपयोग कर सकते हैं जो लिखते समय स्पेलिंग त्रुटियों और व्याकरण की समस्याओं की जांच करते हैं। ऐसे लिंटर्स भी हैं जो आपके Markdown फॉर्मेटिंग की जांच करते हैं।

उदाहरण के लिए, VSCode आपको एडिटर में सीधे Markdown फाइलों का पूर्वावलोकन करने की अनुमति देता है, और इसमें Markdownlint लिंटर के लिए एक एक्सटेंशन है, जो आपके Markdown सिंटैक्स में त्रुटियों की जांच करता है।

Vale नामक एक लोकप्रिय प्रोज़ लिंटर भी है, जिसके VSCode और अन्य एडिटर्स में एक्सटेंशन हैं।

अपने कोड एडिटर में Markdown लिखने का एक और बोनस यह है कि आपको अपने प्रोजेक्ट के लिए डॉक्स और कोड लिखने के लिए एडिटर्स के बीच स्विच करने की आवश्यकता नहीं है। अपने डॉक्स को अपने Rails ऐप के समान डायरेक्टरी में स्टोर करके, आप डॉक्यूमेंटेशन लिखते समय कोड देखने के लिए स्प्लिट लेआउट का उपयोग कर सकते हैं।

परिवर्तन कमिट करना

आपने VSCode में एक नया दस्तावेज़ लिखा है और इसे स्पेलिंग गलतियों और सिंटैक्स त्रुटियों के लिए जांचा है। अगला कदम एक नई ब्रांच बनाना और परिवर्तन को Git में कमिट करना है:

git checkout -b docs/blog-posts git add docs/blog_posts.md git commit -m "Create doc: Blog Posts" git push -u origin docs/blog-posts 

इस कमिट को रिमोट GitHub रिपॉजिटरी में docs/blog-post ब्रांच पर पुश करें।

अंत में, GitHub पर, अपनी नई ब्रांच और मास्टर (या मेन) ब्रांच के बीच एक पुल रिक्वेस्ट बनाएं। यह पुल रिक्वेस्ट आपके परिवर्तनों की समीक्षा और अनुमोदन की अनुमति देता है जैसे प्रोजेक्ट में किसी अन्य कोड की।

डॉक्स की समीक्षा और अनुमोदन

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

हर किसी द्वारा फाइल में किए गए परिवर्तनों का ट्रैक रखें, और किसी भी आगे के संशोधनों पर चर्चा करें जिनकी आवश्यकता है। GitHub और इसी तरह के टूल्स आपको अपनी फाइलों के परिवर्तन इतिहास को देखने की अनुमति देते हैं, जिसमें क्या बदला गया, परिवर्तन कब किया गया, और किसने किया शामिल है।

आप अपने Markdown फाइलों को किसी के द्वारा कोड बेस में मर्ज करने से पहले स्वचालित रूप से जांचने के लिए GitHub Actions भी जोड़ सकते हैं। VSCode में आपके द्वारा उपयोग किए जाने वाले प्रत्येक लिंटर के लिए, यदि वह मौजूद है तो संबंधित GitHub Action जोड़ें:

• Vale action
• Markdownlint action

ये एक्शन आपके Markdown फाइलों को विभिन्न स्पेलिंग और सिंटैक्स त्रुटियों के लिए जांचेंगे इससे पहले कि आपके डॉक्स में परिवर्तन लाइव हों:

Details पर क्लिक करें यह देखने के लिए कि कोई जांच पास क्यों नहीं हो रही है:

अपने पुल रिक्वेस्ट चेक्स में Vale और Markdownlint जोड़ने के लिए, सैंपल रिपॉजिटरी से docs.yml वर्कफ़्लो फाइल कॉपी करें।

Vale एक्शन के काम करने के लिए, आपको अपने रिपॉजिटरी में .github/styles/vocab.txt फाइल बनाने की आवश्यकता हो सकती है। यह शब्दों की एक सूची है (प्रति पंक्ति एक) जिसे Vale द्वारा नजरअंदाज किया जाएगा, जैसे आपकी कंपनी का नाम या आपकी टीम के लोगों के नाम।

यदि आपके पास GitHub Pro, Team, या Enterprise अकाउंट है, तो आप ब्रांच प्रोटेक्शन नियम बना सकते हैं। ये नियम उपयोगकर्ताओं को परिवर्तनों को मर्ज करने से रोकते हैं जब तक कि कुछ आवश्यकताएं पूरी नहीं होतीं, जैसे स्टेटस चेक पास करना या कम से कम एक टीम सदस्य से अनुमोदन प्राप्त करना।

याद रखें कि Netlify चेक्स की सूची में आपकी साइट का प्रीव्यू भी प्रदान करता है, इसलिए समीक्षक परिवर्तनों को मर्ज करने और साइट को पुनः डिप्लॉय करने से पहले जांच सकता है कि सब कुछ अच्छा दिखता है।

आपके डॉक्यूमेंटेशन को अच्छी तरह से समीक्षा करने और फिर मर्ज करने के बाद, Netlify आपकी साइट को पुनः डिप्लॉय करेगा। अपने लाइव Jekyll साइट पर जाएं ताकि परिवर्तन देख सकें।

निष्कर्ष

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

इस लेख में हमने जो Rails ऐप और सैंपल Jekyll साइट बनाई है, उसके लिए सैंपल GitHub रिपॉजिटरी को देखना सुनिश्चित करें। रेपो में सैंपल इश्यूज़ और एक पुल रिक्वेस्ट, साथ ही लेबल्स शामिल हैं। इसमें एक ऑटोमेटेड GitHub प्रोजेक्ट और लेखकों, समीक्षकों, और मेंटेनर्स के लिए कोड बेस में डॉक्यूमेंटेशन जोड़ते समय पालन करने के लिए एक सैंपल पुल रिक्वेस्ट टेम्पलेट भी है।

आगे पढ़ने के लिए, GitLab की डॉक्यूमेंटेशन प्रक्रिया देखें, जिसे अपने स्वयं के विकास के लिए शुरुआती बिंदु के रूप में उपयोग किया जा सकता है। उनके डॉक्यूमेंटेशन दिशानिर्देश भी प्रेरणा प्रदान कर सकते हैं।