रेल में एक दस्तावेज़ीकरण कार्यप्रवाह का निर्माण

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

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

• समस्या ट्रैकर
• संस्करण नियंत्रण उपकरण
• सादा-पाठ फ़ाइलें
• पाठ और कोड संपादक
• स्थिर साइट जेनरेटर
• सतत प्रकाशन

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

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

आवश्यकताएँ

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

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

इस लेख का अनुसरण करने के लिए, कुछ आदेशों के साथ रेल में एक साधारण ब्लॉग एप्लिकेशन बनाएं:

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 db:migrate
rails s

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

एक सामग्री रणनीति बनाना

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

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

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

उदाहरण के लिए, कल्पना करें कि आपके पास एक एपीआई के साथ एक रेल ऐप है। ग्राहकों के लिए, आप अपनी सभी UI सुविधाओं के लिए एक सार्वजनिक उपयोगकर्ता मार्गदर्शिका विकसित करना चाह सकते हैं। एक उपयोगकर्ता कहानी हो सकती है, "एक उपयोगकर्ता के रूप में, मैं एक ब्लॉग पोस्ट बनाना चाहता हूँ।"

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

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

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

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

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

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

• Google डेवलपर दस्तावेज़ीकरण शैली मार्गदर्शिका
• GitLab दस्तावेज़ीकरण शैली मार्गदर्शिका
• माइक्रोसॉफ्ट राइटिंग स्टाइल गाइड

आरंभ करने में आपकी सहायता करने के लिए सामग्री रणनीति पर कुछ और पठन यहां दिए गए हैं:

• डेवलपर पोर्टल के साथ DX सामग्री रणनीति
• प्रलेखन सामग्री रणनीति पर प्राइमर

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

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

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

जेकिल

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

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

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

gem install jekyll bundler

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

jekyll new docs
cd docs
bundle exec jekyll serve

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

यह ट्यूटोरियल just-the-docs . का उपयोग करेगा थीम। इसे स्थापित करने के लिए, /docs . से निम्नलिखित चलाएँ निर्देशिका:

bundle add just-the-docs

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

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

title: Docs Site
email: [email protected]
description: >-
  A Jekyll docs site for a Rails app.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. https://example.com
twitter_username: ""
github_username: ""

# Build settings
theme: just-the-docs

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

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

---
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!

अपना नया नमूना दस्तावेज़ देखने के लिए सर्वर को फिर से प्रारंभ करें:

अब आपके पास /docs . में एक मूल Jekyll साइट है आपके रेल ऐप निर्देशिका में फ़ोल्डर! Jekyll विषय को अनुकूलित करने या अपना स्वयं का लिखने में सहायता के लिए Jekyll दस्तावेज़ देखें।

यार्ड

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

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

# 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

  # code omitted

end

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

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

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

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

आरडीओसी या अन्य सिंटैक्स का उपयोग करके अधिक जटिल दस्तावेज तैयार किए जा सकते हैं (यार्ड दस्तावेज देखें), लेकिन हम यहां मौजूदा दस्तावेज के साथ रहेंगे।

Jekyll सर्वर को प्रारंभ करें और localhost:4000/dev पर नेविगेट करें अपना यार्ड-जनरेटेड दस्तावेज़ देखने के लिए:

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

# Aux links for the upper right navigation
aux_links:
  "Developer Documentation":
    - "/dev"

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

Netlify के साथ निरंतर प्रकाशन और परिनियोजन

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

अब तक हम जिस साइट का निर्माण कर रहे हैं, वह Netlify:Docs Site द्वारा होस्ट की गई है।

अपनी डॉक्स साइट के लिए 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 साइट बनाते समय कुछ सेटिंग उपलब्ध नहीं हैं, तो तैनाती . क्लिक करें अभी के लिए। फिर आप इसे रद्द कर सकते हैं और तैनाती सेटिंग . पर वापस लौट सकते हैं . मूल निर्देशिका को docs . पर सेट करें यह सुनिश्चित करने के लिए कि Netlify आपके रेल ऐप के बजाय आपकी Jekyll डॉक्स साइट को तैनात करता है।

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

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

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

GitHub में एक संपादकीय वर्कफ़्लो सेट करना

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

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

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

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

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

समस्याएं और लेबल

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

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

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

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

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

कार्यप्रवाह का प्रबंधन

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

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

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

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

दस्तावेज़ीकरण बनाना

यह खंड आलेखन से लेकर प्रकाशन तक, दस्तावेज़ीकरण के निर्माण को और अधिक विस्तार से बताता है।

दस्तावेज़ लिखना और संशोधित करना

आपके संपादकीय कार्यप्रवाह में पहला कदम कुछ दस्तावेज़ लिखना है। दस्तावेज़ीकरण लिखने की युक्तियों के लिए, दस्तावेज़ लिखें से दस्तावेज़ीकरण लिखने के लिए एक शुरुआती मार्गदर्शिका देखें।

उदाहरण के लिए, अपने रेल ब्लॉग ऐप के बारे में एक लेख बनाने के लिए, blog-posts.md नामक एक नई मार्कडाउन फ़ाइल बनाएं। आपके Jekyll docs . में निर्देशिका:

---
layout: default
title: Blog Posts
nav_order: 1
---

## Creating a Blog Post

...

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

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

वेले नामक एक लोकप्रिय गद्य लिंटर भी है, जिसका VSCode और अन्य संपादकों में विस्तार है।

अपने कोड संपादक में मार्कडाउन लिखने का एक और बोनस यह है कि आपको अपने प्रोजेक्ट के लिए डॉक्स और कोड लिखने के लिए संपादकों के बीच स्विच करने की आवश्यकता नहीं है। आपके दस्तावेज़ उसी निर्देशिका में संग्रहीत हैं जिसमें आपके 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

इस कमिटमेंट को docs/blog-post . पर पुश करें दूरस्थ GitHub रिपॉजिटरी में शाखा।

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

दस्तावेज़ों की समीक्षा करना और उनका अनुमोदन करना

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

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

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

• वेल एक्शन
• मार्कडाउनलिंट कार्रवाई

आपके दस्तावेज़ में किए गए परिवर्तनों के लाइव होने से पहले ये क्रियाएं आपकी मार्कडाउन फ़ाइलों की विभिन्न वर्तनी और सिंटैक्स त्रुटियों के लिए जाँच करेंगी:

विवरण Click क्लिक करें यह देखने के लिए कि चेक क्यों पास नहीं हो रहा है:

अपने पुल अनुरोध जांच में Vale और Markdownlint जोड़ने के लिए, नमूना संग्रह से docs.yml वर्कफ़्लो फ़ाइल की प्रतिलिपि बनाएँ।

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

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

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

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

निष्कर्ष

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

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

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