রেলে একটি ডকুমেন্টেশন ওয়ার্কফ্লো তৈরি করা

আধুনিক ডকুমেন্টেশন ওয়ার্কফ্লোগুলি সফ্টওয়্যার উন্নয়ন কর্মপ্রবাহের সাথে ক্রমবর্ধমানভাবে জড়িত হয়ে উঠছে। আপনি গিটহাব বা জিরাতে ডকুমেন্টেশন সমস্যাগুলি ট্র্যাক করতে পারেন, অথবা আপনি কোড মন্তব্য বা মার্কডাউন ফাইলগুলিতে ডক্স লিখতে পারেন। আপনার দলের বিকাশকারীরা প্রযুক্তিগত লেখকদের সাথে সরাসরি কাজ করতে পারে বা তারা স্বাধীনভাবে ডক্স লিখতে পারে। ডক্স প্রায়ই কোড রিপোজিটরিতে সংরক্ষণ করা হয়, লিন্টার ব্যবহার করে গুণমানের জন্য পরীক্ষা করা হয় এবং স্ট্যাটিক সাইটগুলিতে ক্রমাগত প্রকাশিত হয়। প্রযুক্তিগত লেখকরা সম্প্রতি ডক্স-লাইক-কোড শব্দটি তৈরি করেছেন অথবা ডক্স-এ-কোড এই ধরনের কর্মপ্রবাহ বর্ণনা করতে।

ডক্স-এ-কোড অটোমেশন দ্বারা সংজ্ঞায়িত করা হয়। পরিচিত ডেভেলপমেন্ট টুল ব্যবহার করে ডকুমেন্টেশন তৈরি করা, আপডেট করা, পর্যালোচনা করা এবং অনুমোদন করা জড়িত:

• ইস্যু ট্র্যাকার
• সংস্করণ নিয়ন্ত্রণ সরঞ্জাম
• প্লেন-টেক্সট ফাইল
• টেক্সট এবং কোড এডিটর
• স্ট্যাটিক সাইট জেনারেটর
• নিরবিচ্ছিন্ন প্রকাশনা

দস্তাবেজগুলি সম্পর্কিত কোডের মতো একই সংগ্রহস্থলে সংরক্ষণ করা যেতে পারে, এটি নিশ্চিত করা সহজ করে যে ডক্সগুলি কোডের পাশাপাশি আপডেট করা হয়েছে৷

এই কর্মপ্রবাহ নমনীয় এবং সরঞ্জাম এবং পদ্ধতির অনেক সংমিশ্রণে অভিযোজিত। দৃষ্টান্তের উদ্দেশ্যে, এই টিউটোরিয়ালটি Jekyll-এর মতো রুবি-ভিত্তিক সরঞ্জামগুলি ব্যবহার করে একটি Rails অ্যাপের জন্য একটি ডক্স-এ-কোড ওয়ার্কফ্লো তৈরি করে। ডক্সগুলি GitHub-এ অ্যাপের পাশাপাশি সংরক্ষণ করা হয় এবং GitHub সমস্যা, লেবেল, প্রকল্প এবং পুল অনুরোধ পর্যালোচনা ব্যবহার করে পরিচালিত হয়। এই উদাহরণটি ডক্স-এ-কোড নীতিগুলিকে চিত্রিত করে যা অন্যান্য সরঞ্জামগুলির সাথে খাপ খাইয়ে নেওয়া যেতে পারে এবং অন্যান্য কর্মপ্রবাহের সাথে একত্রিত হতে পারে৷

পূর্বশর্ত

এই গাইড ডেভেলপারদের জন্য উদ্দেশ্যে করা হয়. আপনার নিম্নলিখিত সরঞ্জামগুলির সাথে পরিচিত হওয়া উচিত:গিট, কোড এডিটর এবং মার্কডাউন। এই নিবন্ধটি বর্ণনা করে যে কিভাবে একটি ডকুমেন্টেশন ওয়ার্কফ্লো তৈরি করতে এই টুলগুলি ব্যবহার করতে হয়৷

এই নিবন্ধটির সাথে রয়েছে একটি লাইভ নমুনা সাইট, 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 db:migrate
rails s

localhost:3000-এ নেভিগেট করুন . আপনার পোস্টগুলির একটি খালি তালিকা এবং একটি নতুন পোস্ট তৈরি করার জন্য একটি লিঙ্ক দেখতে হবে৷

একটি বিষয়বস্তুর কৌশল তৈরি করা

পরিকল্পনা একটি ডকুমেন্টেশন ওয়ার্কফ্লো বিকাশের প্রথম ধাপ, ঠিক যেমন এটি সফ্টওয়্যারের সাথে। আপনার ডক্সের পরিকল্পনায় একটি বিষয়বস্তু কৌশল অন্তর্ভুক্ত করা উচিত, যা নির্ধারণ করে যে কোন বিষয়গুলি নথিভুক্ত করা দরকার এবং কিভাবে।

একটি বিষয়বস্তু কৌশল বিকাশ শুরু করতে, নিম্নলিখিত প্রশ্নের উত্তর দিন:

• আপনার অভিপ্রেত শ্রোতা কে?
  • তারা কি ডেভেলপার, কম প্রযুক্তিগত ব্যবহারকারী, নাকি উভয়ই?
  • তাদের কি আপনার কোড বা ডক্সে অবদান রাখার অনুমতি দেওয়া হয়েছে?
  • এগুলি কি আপনার কোম্পানির অভ্যন্তরীণ বা বাহ্যিক নাকি উভয়ই?
• ব্যবহারকারীরা কী অর্জন করার চেষ্টা করছেন?
• আপনার ডক্সের সাথে পরামর্শ করে ব্যবহারকারীরা কোন সমস্যাগুলি সমাধান করার চেষ্টা করছেন?
• ব্যবহারকারীরা কীভাবে আপনার ডক্সের সাথে পরামর্শ করবে?
  • একটি সাধারণ রিডমি কি যথেষ্ট হবে?
  • ডকুমেন্টেশন অ্যাক্সেস করার জন্য ব্যবহারকারীদের কি বিশেষ অনুমতির প্রয়োজন হবে?

উদাহরণস্বরূপ, কল্পনা করুন আপনার কাছে একটি সহগামী API সহ একটি Rails অ্যাপ আছে। গ্রাহকদের জন্য, আপনি আপনার সমস্ত UI বৈশিষ্ট্যগুলির জন্য একটি সর্বজনীন ব্যবহারকারী গাইড বিকাশ করতে চাইতে পারেন৷ একটি ব্যবহারকারীর গল্প হতে পারে, "একজন ব্যবহারকারী হিসাবে, আমি একটি ব্লগ পোস্ট তৈরি করতে চাই।"

আপনি বিকাশকারীদের জন্য রেফারেন্স ডকুমেন্টেশনও তৈরি করতে পারেন। একটি বিকাশকারীর গল্প হতে পারে, "একজন বিকাশকারী হিসাবে, আমি একটি নির্দিষ্ট ব্যবহারকারীর সমস্ত ব্লগ পোস্ট পুনরুদ্ধার করতে চাই।"

আপনি একটি স্ট্যাটিক সাইট জেনারেটর ব্যবহার করতে পারেন, যেমন জেকিল বা ওয়ার্ডপ্রেস, একটি ব্র্যান্ডেড, ব্যবহারকারী-বান্ধব পরিবেশে ব্যবহারকারী ডক্স উপস্থাপন করতে। আপনার অভ্যন্তরীণ বিকাশকারীদের জন্য, একটি সাধারণ YARD-উত্পন্ন সাইট যথেষ্ট হতে পারে। এই টিউটোরিয়ালটি আপনাকে উভয়ের উদাহরণ দেখাবে৷

ডকুমেন্টেশন আপনার বর্তমান কর্মপ্রবাহের সাথেও একত্রিত করা যেতে পারে। উদাহরণস্বরূপ, যদি আপনার দল 2-সপ্তাহের স্প্রিন্টে কোড লিখে, তাহলে একই সময়সূচীতে আপনার ডকুমেন্টেশন পরিচালনা করার কথা বিবেচনা করুন।

আপনি কোড সমস্যাগুলির পাশাপাশি ডকুমেন্টেশন সমস্যাগুলিও ট্র্যাক করতে পারেন। প্রতিটি ডক্স বৈশিষ্ট্য বা বাগের জন্য একটি সমস্যা তৈরি করুন৷ একটি বৈশিষ্ট্য একটি নতুন নিবন্ধ বা বিষয়বস্তুর বিভাগ হবে, এবং একটি বাগ কোন ত্রুটি, বাদ দেওয়া, টাইপো বা অন্য সমস্যার সমাধানের প্রয়োজন হবে৷

প্রতিক্রিয়া সংগ্রহ করা একটি বিষয়বস্তু কৌশলের একটি গুরুত্বপূর্ণ অংশ। ব্যবহারকারীদের প্রতিটি ডক পৃষ্ঠায় প্রতিক্রিয়া সহ আপনার সাথে যোগাযোগ করতে বা GitHub এর মাধ্যমে ডক্সে অবদান রাখার জন্য একটি উপায় যোগ করার কথা বিবেচনা করুন৷ একটি প্রতিক্রিয়া বোতাম সাধারণত শুধুমাত্র একটি ফর্ম যা একটি কোম্পানির ইমেল ঠিকানায় যায়; এই কাজের জন্য নিযুক্ত ব্যক্তি(গুলি) তারপর প্রতিটি প্রতিক্রিয়া আইটেম নিতে পারে এবং পর্যালোচনা এবং বাস্তবায়নের জন্য এটিকে জিরা বা গিটহাব ইস্যুতে পরিণত করতে পারে৷

একটি সামঞ্জস্যপূর্ণ শৈলী এবং সুনির্দিষ্ট পরিভাষার ব্যবহার নিশ্চিত করতে, একটি কোম্পানির শৈলী নির্দেশিকা তৈরি করুন বা বিদ্যমান একটি অনুসরণ করুন। এখানে ডকুমেন্টেশন স্টাইল গাইডের কিছু উদাহরণ রয়েছে যা বেশিরভাগ সফ্টওয়্যার প্রকল্পের জন্য কাজ করবে:

• গুগল ডেভেলপার ডকুমেন্টেশন স্টাইল গাইড
• GitLab ডকুমেন্টেশন স্টাইল গাইড
• মাইক্রোসফট রাইটিং স্টাইল গাইড

আপনাকে শুরু করতে সাহায্য করার জন্য এখানে বিষয়বস্তু কৌশল সম্পর্কে আরও কিছু পড়া রয়েছে:

• ডেভেলপার পোর্টালগুলির সাথে DX বিষয়বস্তু কৌশল
• প্রাইমার অন ডকুমেন্টেশন কন্টেন্ট স্ট্র্যাটেজি

একটি ডক্স সাইট তৈরি করা

আপনার বিষয়বস্তু কৌশল থেকে, আপনি নির্ধারণ করতে পারেন কিভাবে আপনার নথিগুলি উদ্দিষ্ট দর্শকদের কাছে উপস্থাপন করা হবে। কে নির্ধারণ করা হচ্ছে আপনার ডক্স লিখবে এছাড়াও এই সিদ্ধান্ত জানাতে সাহায্য করবে. উদাহরণস্বরূপ, যদি বিকাশকারী এবং অবদানকারীরা কোড মন্তব্যে ডকুমেন্টেশন লিখতে থাকে, তাহলে এই মন্তব্যগুলি থেকে একটি সাধারণ স্ট্যাটিক ডক্স সাইট তৈরি করতে RDoc বা YARD ব্যবহার করা যেতে পারে। যদি ব্যবহারকারীর ডকুমেন্টেশনগুলি মার্কডাউন ফাইলগুলিতে লেখা হয়, তাহলে জেকিলের মতো একটি স্ট্যাটিক সাইট জেনারেটর আপনার ডক্স প্রকাশ করার জন্য ভাল পছন্দ হবে। অবশ্যই, আপনি স্ক্র্যাচ থেকে একটি সাইটও তৈরি করতে পারেন যা আপনার দল এবং আপনার প্রকল্পের জন্য কাজ করে।

এই নিবন্ধটি একটি Rails অ্যাপের জন্য উভয় ধরনের ডকুমেন্টেশন সাইটগুলিকে চিত্রিত করতে Jekyll এবং YARD ব্যবহার করে৷ মনে রাখবেন যে জেকিল রুবি-ভিত্তিক এবং একটি রেল অ্যাপের সাথে ভালভাবে সংহত৷

Jekyl

জেকিলের উদ্দেশ্য হল প্লেইন টেক্সটকে একটি স্ট্যাটিক ওয়েবসাইটে রূপান্তর করা। জেকিল একটি _site তৈরি করে স্ট্যাটিক সাইট ফাইল ধারণকারী ফোল্ডার যে কোনো হোস্টিং পরিষেবা দ্বারা প্রকাশ করা যেতে পারে. এই ফাইলগুলিকে GitHub-এ পুশ করার অর্থ হল আপনি আপনার ডক্স প্রকাশ করতে নেটলিফাই-এর মতো অবিচ্ছিন্ন প্রকাশনা সরঞ্জামগুলি ব্যবহার করতে পারেন৷

জেকিলের সাথে সবচেয়ে সহজ কর্মপ্রবাহের মধ্যে রয়েছে মার্কডাউন ফাইলগুলিতে ডক্স লেখা এবং সেগুলিকে গিটহাবে ঠেলে দেওয়া। আপনি যদি Netlify ব্যবহার করেন, আপনি সংগ্রহস্থলে এই পরিবর্তনগুলি মার্জ করার সময় এটি স্বয়ংক্রিয়ভাবে সাইটটিকে স্থাপন করে। এই প্রক্রিয়াটি পরবর্তী বিভাগে আরও বিশদে বর্ণনা করা হয়েছে৷

একটি Jekyll সাইট তৈরি করতে, আপনার Rails অ্যাপের রুট ডিরেক্টরি থেকে Jekyll এবং Bundler ইনস্টল করুন (যেমন, /blog ):

gem install jekyll bundler

একটি জেকিল সাইট তৈরি করতে এবং স্থানীয় ডেভেলপমেন্ট সার্ভার থেকে চালানোর জন্য শুধুমাত্র তিনটি কমান্ডের প্রয়োজন হয়:

jekyll new docs
cd docs
bundle exec jekyll serve

এটি একটি /docs তৈরি করে একটি ন্যূনতম জেকিল সাইট ধারণকারী ডিরেক্টরি (ডিফল্ট হল মিনিমা নামে একটি ব্লগ থিম)। আপনি এটিকে আপনার কাস্টম জেকিল ডক্স সাইটের ভিত্তি হিসাবে ব্যবহার করতে পারেন। বিকল্পভাবে, আপনি একটি ডক্স থিম ইনস্টল করতে পারেন, যেমন just-the-docs , যা সাইডবার নেভিগেশন এবং সাইট অনুসন্ধান কার্যকারিতার সাথে আসে।

এই টিউটোরিয়ালটি just-the-docs ব্যবহার করবে থিম এটি ইনস্টল করতে, /docs থেকে নিম্নলিখিতটি চালান ডিরেক্টরি:

bundle add just-the-docs

minima সরান Gemfile থেকে থিম যেহেতু এটি ডিফল্ট থিম আপনি আর ব্যবহার করবেন না। এছাড়াও আপনি posts মুছে ফেলতে পারেন ডিরেক্টরি।

এরপর, Jekyll এর _config.yml-এ এই থিমটি যোগ করুন ফাইল আপনি এখানে থাকাকালীন আপনার সাইটের শিরোনাম এবং বিবরণ কাস্টমাইজ করতে পারেন:

title: Docs Site
email: your-email@example.com
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

সার্ভার আবার শুরু করুন, এবং আপনি একটি বেশিরভাগ খালি ডক্স সাইট দেখতে পাবেন:

আপনার মার্কডাউন ফাইলগুলি কোন ডিরেক্টরিতে রাখা উচিত তা দেখতে আপনার জেকিল থিমের ডকুমেন্টেশন পরীক্ষা করুন। 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-এ একটি বেসিক জেকিল সাইট আছে আপনার Rails অ্যাপ ডিরেক্টরিতে ফোল্ডার! Jekyll থিম কাস্টমাইজ করা বা আপনার নিজের লেখার জন্য সাহায্যের জন্য Jekyll ডক্স দেখুন।

YARD

ডকুমেন্টেশন জেনারেটর, যেমন Rdoc এবং YARD, কোড মন্তব্য থেকে বিকাশকারী ডকুমেন্টেশন তৈরি করে। আপনি YARD ব্যবহার করে একটি স্বতন্ত্র ডক্স সাইট তৈরি করতে পারেন, যা Rdoc এবং অন্যান্য সিনট্যাক্স গ্রহণ করে। এই উদাহরণে, আমরা আমাদের বিদ্যমান জেকিল সাইটে YARD ডকুমেন্টেশন যোগ করব। জেকিল 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

  # code omitted

end

একটি ডক্স সাইট তৈরি করতে YARD কীভাবে এই মন্তব্যগুলি ব্যবহার করে তা দেখতে, yard doc চালান অথবা yardoc আপনার Rails অ্যাপের রুট ডিরেক্টরি থেকে কমান্ড:

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

যদি yardoc কমান্ড কাজ করে না, bundle install yard দিয়ে YARD রত্নটি ইনস্টল করুন .

YARD তার আউটপুট ফাইলগুলিকে output-dir এ রাখবে , যা জেকিল ডিরেক্টরি /docs/dev এ সেট করা আছে উপরের কমান্ডে। জেকিল এখন /dev এর বেস পাথ সহ YARD-এর সাইট ফাইলগুলি প্রকাশ করতে পারে .

আরও জটিল ডকুমেন্টেশন RDoc বা অন্যান্য সিনট্যাক্স ব্যবহার করে তৈরি করা যেতে পারে (YARD ডকুমেন্টেশন দেখুন), কিন্তু আমরা এখানে বিদ্যমান ডকুমেন্টেশনের সাথেই থাকব।

জেকিল সার্ভার শুরু করুন এবং localhost:4000/dev-এ নেভিগেট করুন আপনার ইয়ার্ড-জেনারেটেড ডকুমেন্টেশন দেখতে:

এই মুহুর্তে, প্রধান জেকিল সাইট থেকে এই বিকাশকারী ডক্সগুলিতে নেভিগেট করার কোন উপায় নেই৷ ডেভেলপার ডক্সে জেকিল সাইট থেকে একটি লিঙ্ক যোগ করতে, docs/_config.yml-এ নিম্নলিখিত যোগ করুন :

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

এটি জেকিল এবং ইয়ার্ডের আলোচনার সমাপ্তি ঘটায়। এখন আপনার ডক্স সাইটটি সেট আপ করা হয়েছে, বিকাশকারী এবং লেখকরা কেবল মার্কডাউন ফাইলগুলিতে (বা কোড মন্তব্য) সামগ্রী লিখতে পারেন এবং সেগুলিকে গিটহাবে ঠেলে দিতে পারেন৷ পরের বিভাগে ব্যাখ্যা করা হয়েছে কিভাবে এই ডক্সগুলিকে ক্রমাগত প্রকাশনার সাথে স্থাপন করা যায়।

নেটলিফাই এর সাথে ক্রমাগত প্রকাশনা এবং স্থাপনা

অবিচ্ছিন্ন প্রকাশনা ডক্স সাইটগুলির জন্য সুবিধাজনক কারণ ডক্সে পরিবর্তনগুলি অনুমোদিত এবং সংগ্রহস্থলে একত্রিত হলে লাইভ সাইটটি স্বয়ংক্রিয়ভাবে আপডেট হতে পারে। এই টিউটোরিয়ালটি এই উদ্দেশ্যে নেটলিফাই ব্যবহার করে, তবে অন্যান্য সরঞ্জাম উপলব্ধ রয়েছে, যেমন গিটহাব পেজ, গিটল্যাব পেজ এবং ফায়ারবেস।

আমরা এখন পর্যন্ত যে সাইটটি তৈরি করছি সেটি 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 সাইট তৈরি করার সময় কিছু সেটিংস উপলব্ধ না হলে, ডিপ্লয় এ ক্লিক করুন আপাতত তারপর আপনি এটি বাতিল করতে পারেন এবং ডিপ্লয় সেটিংস-এ ফিরে যেতে পারেন৷ . বেস ডিরেক্টরিকে docs এ সেট করুন Netlify আপনার Rails অ্যাপের পরিবর্তে আপনার Jekyll ডক্স সাইট স্থাপন করে তা নিশ্চিত করতে।

Netlify আপনার জেকিল সাইট স্থাপন করা শেষ হলে, সবকিছু ঠিক আছে কিনা তা নিশ্চিত করতে লাইভ সাইটে নেভিগেট করুন।

Netlify ব্যবহার করার একটি সুবিধা হল এটি প্রতিটি পুল অনুরোধ থেকে সরাসরি একটি লাইভ প্রিভিউ লিঙ্ক প্রদান করে:

তারপরে আপনি পরীক্ষা করতে পারেন যে পুল অনুরোধটি মার্জ করার আগে আপনার পরিবর্তনগুলি সঠিকভাবে প্রকাশ করা হবে এবং আপনার সাইটের পুনঃনিয়োগ ট্রিগার করুন৷ পরবর্তী বিভাগে এই কর্মপ্রবাহকে আরো বিস্তারিতভাবে কভার করে।

GitHub এ একটি সম্পাদকীয় কার্যপ্রবাহ সেট আপ করা

ডকুমেন্টেশন লেখার একটি কৌশল এবং এটিকে প্রকাশ করার জন্য একটি সাইট সহ, আপনি ডক্স লেখা শুরু করতে এবং সেগুলিকে আপনার সফ্টওয়্যার ওয়ার্কফ্লোতে একীভূত করতে প্রস্তুত৷

একটি সাধারণ সম্পাদকীয় কার্যপ্রবাহের মধ্যে একটি নথির খসড়া তৈরি করা, নথিটি পর্যালোচনা করা এবং তারপরে এটি প্রকাশ করা জড়িত। লেখকদের তাদের কাজের নিজস্ব পর্যালোচনা করা উচিত, তবে সম্পাদক, পরিচালক এবং স্টেকহোল্ডাররা প্রায়ই চূড়ান্ত পর্যালোচনা প্রক্রিয়ার অংশ। যেহেতু এটি সফ্টওয়্যার ডেভেলপমেন্ট প্রক্রিয়ার অনুরূপ, আপনি প্রক্রিয়াটিকে আরও দক্ষ করার জন্য সফ্টওয়্যার বিকাশের সরঞ্জামগুলি ব্যবহার করতে পারেন৷

এখানে GitHub ব্যবহার করে একটি দলের জন্য সম্পাদকীয় কার্যপ্রবাহের একটি উদাহরণ রয়েছে:

1. [লেখক] একটি ডকুমেন্টেশন বৈশিষ্ট্য অনুরোধ বা বাগ অনুযায়ী একটি ফাইল তৈরি বা আপডেট করুন (যেমন একটি গিটহাব সমস্যায় উল্লেখ করা হয়েছে)।
2. [লেখক] একটি GitHub শাখায় পরিবর্তনটি পুশ করুন।
3. [লেখক] একটি টান অনুরোধ খুলুন।
4. [পর্যালোচক] পরিবর্তনগুলি পর্যালোচনা করুন৷
৷
5. [পর্যালোচক/রক্ষণাবেক্ষণকারী] রিপোজিটরিতে পরিবর্তনগুলি মার্জ করুন, যা ডক্স সাইটের একটি নতুন বিল্ড ট্রিগার করবে৷

GitHub স্বয়ংক্রিয়ভাবে আপনার বিষয়বস্তুর পরিবর্তনের ইতিহাস পরিচালনা করে, যা একটি ডক্স-এ-কোড ওয়ার্কফ্লোতেও গুরুত্বপূর্ণ। আপনি দেখতে পারেন কি পরিবর্তন করা হয়েছে, কে এটি পরিবর্তন করেছে, কখন এটি পরিবর্তন করা হয়েছে, সেইসাথে কেন বা কিভাবে এটি পরিবর্তন করা হয়েছে (যদি মন্তব্য, আলোচনা, বা সম্পর্কিত সমস্যা উল্লেখ করা হয়)। এটি আপনার দলের সকল সদস্যদের যেকোন সময়ে দেখার জন্য এক জায়গায় সংরক্ষণ করা হয়।

সমস্যা এবং লেবেল

আপনি নতুন ডকুমেন্টেশনের জন্য একই সমস্যা টেমপ্লেট ব্যবহার করতে পারেন যা আপনি কোডের জন্য ব্যবহার করবেন। এটি সম্প্রদায়ের সদস্যদের অনুপস্থিত হতে পারে এমন ডকুমেন্টেশনের অনুরোধ করতে বা ত্রুটির দলকে অবহিত করার অনুমতি দেয়। ম্যানেজাররাও ডেভেলপার বা লেখকদের ডকুমেন্টেশন টাস্কে বরাদ্দ করতে সমস্যা ব্যবহার করতে পারেন।

কোড সমস্যা থেকে ডক্স সমস্যাগুলিকে আলাদা করতে, আপনি লেবেল ব্যবহার করতে পারেন। একটি documentation যোগ করুন লেবেল নির্দেশ করে যে এটি ডক্সের সাথে সম্পর্কিত। এছাড়াও আপনি নির্দিষ্ট ডক্স সমস্যার জন্য লেবেল তৈরি করতে পারেন, যেমন docs::feature অথবা docs::fix .

আপনি সমস্যার শিরোনাম বা উপযুক্ত লেবেল সম্পর্কিত আপনার সমস্যার টেমপ্লেটগুলিতে নির্দেশাবলী যোগ করতে পারেন, ঠিক যেমন আপনি কোড-সম্পর্কিত সমস্যাগুলির জন্য চান৷

ওয়ার্কফ্লো লেবেল, যেমন docs::in progress এবং docs::in review , এছাড়াও দরকারী. তারা বর্তমানে যা কাজ করা হচ্ছে তা প্রতিফলিত করে৷

আপনার ডকুমেন্টেশন প্রক্রিয়া সংজ্ঞায়িত করার সময়, এই লেবেলগুলি এবং কখন পরিবর্তন করার জন্য কে দায়ী তা নির্দিষ্ট করতে ভুলবেন না। উদাহরণ স্বরূপ, যে ব্যক্তি খসড়া লিখছেন তিনি লেবেলটিকে docs::in progress-এ পরিবর্তন করবেন যখন তারা খসড়া লেখা শুরু করে। যখন পর্যালোচক খসড়াটি পান, তখন পর্যালোচকের উচিত সমস্যা লেবেলটিকে docs::in review এ পরিবর্তন করা .

ওয়ার্কফ্লো পরিচালনা

ছোট দল এবং প্রকল্পগুলির জন্য, GitHub প্রকল্পগুলি ব্যবহার করা হল GitHub থেকে সরাসরি আপনার সম্পাদকীয় সামগ্রী পরিচালনা করার একটি সুবিধাজনক উপায়। এগুলি প্রজেক্ট ম্যানেজমেন্ট বোর্ডের মতো, যেমন ট্রেলোতে, তবে কলামগুলি সরাসরি সমস্যাগুলির সাথে লিঙ্ক করা যেতে পারে এবং অনুরোধগুলি পুল করতে পারে৷

উদাহরণস্বরূপ, "রিভিউ সহ স্বয়ংক্রিয় কানবান" টেমপ্লেটটি ব্যবহার করুন যাতে নতুন সমস্যা এবং পুল অনুরোধগুলি স্বয়ংক্রিয়ভাবে বোর্ডে যুক্ত হয়৷ যখন একজন পর্যালোচক একটি পর্যালোচনা শুরু করেন বা একটি পুল অনুরোধ অনুমোদন করেন, ইস্যু কার্ডটি পরবর্তী কলামে চলে যায়। এটি আপনাকে সক্রিয় সমস্যাগুলির ট্র্যাক রাখতে দেয় এবং সেগুলি কোথায় সম্পাদকীয় প্রক্রিয়ায় রয়েছে৷

বৃহত্তর প্রজেক্টের জন্য যেগুলোতে ডক্স ছাড়াও আরও অনেক কিছু আছে, project-bot ব্যবহার করুন অটোমেশন নিয়ম সেট আপ করতে GitHub অ্যাপ। উদাহরণস্বরূপ, একটি নির্দিষ্ট লেবেল যোগ করা বা একটি নির্দিষ্ট পর্যালোচককে বরাদ্দ করা স্বয়ংক্রিয় কার্ড আন্দোলনকে ট্রিগার করবে। বিকল্পভাবে, আপনি জিরার মতো একটি টুল ব্যবহার করে আপনার বৃহত্তর প্রজেক্ট ম্যানেজমেন্ট ওয়ার্কফ্লোতে ডকুমেন্টেশন ম্যানেজমেন্টকে একীভূত করতে পারেন।

project-bot-এর প্রদর্শনের জন্য নমুনা অ্যাপটি দেখুন একটি GitHub প্রকল্পে অ্যাপ।

ডকুমেন্টেশন তৈরি করা

এই বিভাগে ডকুমেন্টেশন তৈরির রূপরেখা আরো বিস্তারিতভাবে, খসড়া তৈরি থেকে প্রকাশনা পর্যন্ত।

ডক্স লেখা এবং সংশোধন করা

আপনার সম্পাদকীয় কর্মপ্রবাহের প্রথম ধাপ হল কিছু নথি লেখা। ডকুমেন্টেশন লেখার টিপসের জন্য, ডকুমেন্টেশন লেখার জন্য একটি শিক্ষানবিস গাইড দেখুন ডকুমেন্ট লিখুন থেকে।

উদাহরণস্বরূপ, আপনার Rails ব্লগ অ্যাপ সম্পর্কে একটি নিবন্ধ তৈরি করতে, 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 এবং অনুরূপ সরঞ্জামগুলি আপনাকে আপনার ফাইলগুলির পরিবর্তনের ইতিহাস দেখতে দেয়, যার মধ্যে কী পরিবর্তন করা হয়েছিল, কখন পরিবর্তন করা হয়েছিল এবং কে এটি করেছিল৷

কেউ কোড বেসে মার্জ করার আগে আপনার মার্কডাউন ফাইলগুলিকে স্বয়ংক্রিয়ভাবে পরীক্ষা করতে আপনি গিটহাব অ্যাকশনগুলি যোগ করতে পারেন। আপনি VSCode-এ ব্যবহার করেন এমন প্রতিটি লিন্টারের জন্য, সংশ্লিষ্ট গিটহাব অ্যাকশন যোগ করুন যদি এটি বিদ্যমান থাকে:

• ভ্যাল অ্যাকশন
• মার্কডাউনলিন্ট অ্যাকশন

এই ক্রিয়াগুলি আপনার ডক্সে পরিবর্তনগুলি লাইভ হওয়ার আগে বিভিন্ন বানান এবং বাক্য গঠন ত্রুটির জন্য আপনার মার্কডাউন ফাইলগুলি পরীক্ষা করবে:

বিশদ বিবরণ ক্লিক করুন কেন একটি চেক পাস হচ্ছে না তা দেখতে:

আপনার পুল অনুরোধ চেকগুলিতে Vale এবং Markdownlint যোগ করতে, নমুনা সংগ্রহস্থল থেকে docs.yml ওয়ার্কফ্লো ফাইলটি অনুলিপি করুন৷

ভ্যাল অ্যাকশন কাজ করার জন্য, আপনাকে .github/styles/vocab.txt তৈরি করতে হতে পারে আপনার সংগ্রহস্থলে ফাইল। এটি এমন একটি শব্দের তালিকা (প্রতি লাইনে একটি) যা ভ্যালের দ্বারা উপেক্ষা করা হবে, যেমন আপনার কোম্পানির নাম বা আপনার দলের লোকেদের নাম৷

আপনার যদি গিটহাব প্রো, টিম বা এন্টারপ্রাইজ অ্যাকাউন্ট থাকে তবে আপনি শাখা সুরক্ষা নিয়ম তৈরি করতে পারেন। এই নিয়মগুলি ব্যবহারকারীদের পরিবর্তনগুলিকে একত্রিত করতে বাধা দেয় যদি না কিছু প্রয়োজনীয়তা পূরণ না হয়, যেমন স্ট্যাটাস চেক পাস করা বা কমপক্ষে একজন দলের সদস্যের কাছ থেকে অনুমোদন নেওয়া৷

মনে রাখবেন যে Netlify চেকের তালিকায় আপনার সাইটের একটি পূর্বরূপও প্রদান করে, যাতে পর্যালোচক চেক করতে পারেন যে সবকিছু আগে ভালো দেখাচ্ছে। পরিবর্তনগুলি একত্রিত করা এবং সাইটটিকে পুনরায় স্থাপন করা।

আপনি পুঙ্খানুপুঙ্খভাবে পর্যালোচনা করার পরে এবং তারপরে আপনার ডকুমেন্টেশনে পরিবর্তনগুলি একত্রিত করার পরে, Netlify আপনার সাইট পুনরায় স্থাপন করবে। পরিবর্তনগুলি দেখতে আপনার লাইভ জেকিল সাইটে নেভিগেট করুন৷

উপসংহার

আপনার এখন একটি রেল অ্যাপ বা অন্য কোনও প্রকল্পের জন্য গিটহাবে একটি মৌলিক ডকুমেন্টেশন ওয়ার্কফ্লো থাকা উচিত। কোডের মতো ডক্স পরিচালনা করা যতটা সহজ বা জটিল হতে পারে। ছোট প্রকল্পগুলির জন্য, গিটহাবে কিছুটা অটোমেশন আপনার প্রয়োজন হতে পারে। বৃহত্তর প্রকল্পগুলি অন্যান্য বিভাগ এবং দলের সাথে আরও ঘনিষ্ঠভাবে একত্রিত হতে পারে এবং তাই, অন্যান্য সরঞ্জামগুলির সাথে।

Rails অ্যাপের নমুনা GitHub সংগ্রহস্থল এবং আমরা এই নিবন্ধে তৈরি জেকিল সাইটের নমুনা দেখতে ভুলবেন না। রেপোতে নমুনা সমস্যা এবং একটি পুল অনুরোধ, সেইসাথে লেবেল অন্তর্ভুক্ত রয়েছে। এটিতে একটি স্বয়ংক্রিয় GitHub প্রজেক্ট এবং লেখক, পর্যালোচক এবং রক্ষণাবেক্ষণকারীদের কোড বেসে ডকুমেন্টেশন যোগ করার সময় অনুসরণ করার জন্য একটি নমুনা পুল অনুরোধ টেমপ্লেট রয়েছে।

আরও পড়ার জন্য, গিটল্যাবের ডকুমেন্টেশন প্রক্রিয়াটি দেখুন, যা আপনার নিজের বিকাশের জন্য একটি সূচনা পয়েন্ট হিসাবে ব্যবহার করা যেতে পারে। তাদের ডকুমেন্টেশন নির্দেশিকা অনুপ্রেরণা প্রদান করতে পারে।