রেইলস প্রজেক্টের জন্য দক্ষ ডকুমেন্টেশন ওয়ার্কফ্লো ডিজাইন

আধুনিক ডকুমেন্টেশন ওয়ার্কফ্লো তার সাথে সফটওয়্যার ডেভেলপমেন্ট ওয়ার্কফ্লোর সাথে যেনে যেনে গুঁথিয়ে যাচ্ছে। আপনি ডকুমেন্টেশন ইস্যু GitHub বা Jira-এ ট্র্যাক করতে পারেন, অথবা কোড কমেন্ট বা Markdown ফাইলে ডক্স লিখতে পারেন। আপনার টিমের ডেভেলপাররা টেকনিক্যাল রাইটারদের সাথে সরাসরি কাজ করতে পারেন, অথবা স্বাধীনভাবে ডক্স লিখতে পারেন। ডক্স প্রায় কোড রিপোজিটরিতে সংরক্ষিত থাকে, লিন্টারস ব্যবহার করে কোয়ালিটির জন্য টেস্ট করা হয়, এবং স্ট্যাটিক সাইটসে কন্টিনিউয়াসলি পাবলিশ করা হয়। টেকনিক্যাল রাইটাররা gầnে docs-like-code বা docs-as-code শব্দটি খোঁজে বের করেছেন এই টাইপের ওয়ার্কফ্লো বর্ণনা করতে।

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

• ইস্যু ট্র্যাকার
• ভার্সন কন্ট্রোল টুলস
• প্লেইন-টেক্সট ফাইলস
• টেক্সট এবং কোড এডিটর
• স্ট্যাটিক সাইট জেনারেটর
• কন্টিনিউয়াস পাবলিকেশন

ডক্স সংশ্লিষ্ট কোডের সাথে একই রিপোজিটরিতে সংরক্ষিত করা যায়, যা ডক্স কোডের সাথে আপডেটেড রাখা সহজ করে দেয়।

এই ওয়ার্কফ্লো ফ্লেক্সিবল এবং অনেক টুল ও মেথডলজির কম্বিনেশনে অ্যাডাপ্টেবল। ইলাস্ট্রেশন উদ্দেশ্যে, এই টিউটোরিয়াল একটি রেইলস অ্যাপের জন্য docs-as-code ওয়ার্কফ্লো ডেভেলপ করে রুবি-বেজড টুলস ব্যবহার করে, যেমন Jekyll। ডক্স অ্যাপের সাথে GitHub-এ সংরক্ষিত থাকে এবং GitHub ইস্যু, লেবেল, প্রজেক্ট, এবং পুল রিকোয়েস্ট রিভিউ ব্যবহার করে ম্যানেজ করা হয়। এই উদাহরণ docs-as-code প্রিন্সিপ্যাল ইলাস্ট্রেট করে যেগুলো অন্যান্য টুলস এবং ওয়ার্কফ্লোতে অ্যাডাপ্ট করা যায়।

প্রেরিকোয়েজিট

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

এই আর্টিকেলের সাথে একটি লাইভ স্যাম্পল সাইট, 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-এ নেভিগেট করুন। আপনার পোস্টের একটি খালি লিস্ট এবং একটি নতুন পোস্ট তৈরি করার লিংক দেখতে পাবেন।

কন্টেন্ট স্ট্র্যাটেজি তৈরী

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

কন্টেন্ট স্ট্র্যাটেজি ডেভেলপ করা শুরু করতে, নিচের প্রশ্নগুলোর উত্তর দিন:

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

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

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

আপনি একটি স্ট্যাটিক সাইট জেনারেটর, যেমন Jekyll বা WordPress, ব্যবহার করতে পারেন ইউজার ডক্স একটি ব্র্যান্ডেড, ইউজার-ফ্রেন্ডলি এনভায়রনমেন্টে প্রেজেন্ট করতে। আপনার ইন্টারনাল ডেভেলপারদের জন্য, একটি সিম্পল YARD-জেনারেটেড সাইট যথেষ্ট হতে পারে। এই টিউটোরিয়াল আপনাকে উভয় টাইপের উদাহরণ দেখাবে।

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

আপনি কোড ইস্যুর সাথে ডকুমেন্টেশন ইস্যুও ট্র্যাক করতে পারেন। প্রতিটি ডক্স ফিচার বা বাগের জন্য একটি ইস্যু তৈরি করুন। একটি ফিচার হলে একটি নতুন আর্টিকেল বা কন্টেন্ট সেকশন, এবং একটি বাগ হলে যেকোনো এরর, অমিশন, টাইপো, বা অন্যান্য ইস্যু যেগুলো ফিক্স করতে হবে।

ফিডব্যাক সংগ্রহ করা একটি কন্টেন্ট স্ট্র্যাটেজির গুরুত্বপূর্ণ অংশ। প্রতিটি ডক পেজে ইউজারদের ফিডব্যাক দিতে বা GitHub-এর মাধ্যমে ডক্সে কন্ট্রিবিউট করার উপায় যোগ করার কথা ভাবুন। একটি Feedback বাটন সাধারণত শুধু একটি ফর্ম যা কোম্পানির ইমেইল এড্রেসে যায়; এই টাস্কের জন্য অ্যাসাইন করা ব্যক্তি(রা) প্রতিটি ফিডব্যাক আইটেম নিতে পারেন এবং সেটিকে একটি Jira বা GitHub ইস্যুতে রূপান্তর করতে পারেন রিভিউ এবং বাস্তবায়নের জন্য।

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

• Google Developer Documentation Style Guide
• GitLab Documentation Style Guide
• Microsoft Writing Style Guide

কন্টেন্ট স্ট্র্যাটেজি শুরু করতে আরও কিছু রিডিং:

• DX Content Strategy with Developer Portals
• Primer on Documentation Content Strategy

ডক্স সাইট বিল্ড

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

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

Jekyll

Jekyll-এর উদ্দেশ্য হলো প্লেইন টেক্সটকে একটি স্ট্যাটিক ওয়েবসাইটে ট্রান্সফর্ম করা। Jekyll একটি _site ফোল্ডার তৈরি করে স্ট্যাটিক সাইট ফাইলসহ যা যেকোনো হোস্টিং সার্ভিস দ্বারা পাবলিশ করা যায়। এই ফাইলগুলো GitHub-এ পুশ করা মানে আপনি কন্টিনিউয়াস পাবলিকেশন টুলস, যেমন Netlify, ব্যবহার করতে পারেন আপনার ডক্স পাবলিশ করতে।

Jekyll-এর সাথে সিম্পলেস্ট ওয়ার্কফ্লো হলো Markdown ফাইলে ডক্স লিখা এবং GitHub-এ পুশ করা। যদি আপনি Netlify ব্যবহার করেন, এটি অটোমেটিকলি সাইট ডিপ্লয় করবে যখন আপনি এই চেঞ্জগুলো রিপোজিটরিতে মার্জ করবেন। এই প্রসেস পরের সেকশনে আরও ডিটেইলে বর্ণনা করা হয়েছে।

একটি Jekyll সাইট তৈরি করতে, আপনার রেইলস অ্যাপের রুট ডিরেক্টরি থেকে (যেমন /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: >- A Jekyll docs site for a Rails app. 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! 

সার্ভার আবার স্টার্ট করুন আপনার নতুন স্যাম্পল ডক দেখতে:

আপনার এখন আপনার রেইলস অ্যাপ ডিরেক্টরিতে /docs ফোল্ডারে একটি বেসিক Jekyll সাইট আছে! Jekyll থিম কাস্টোমাইজ করতে বা নিজের তৈরি করতে হেল্পের জন্য Jekyll ডক্স দেখুন।

YARD

ডকুমেন্টেশন জেনারেটর, যেমন Rdoc এবং YARD, কোড কমেন্ট থেকে ডেভেলপার ডকুমেন্টেশন জেনারেট করে। আপনি YARD ব্যবহার করে একটি স্ট্যান্ডঅ্যালোন ডক্স সাইট তৈরি করতে পারেন, যা Rdoc এবং অন্যান্য সিনট্যাক্স এক্সেপ্ট করে। এই উদাহরণে, আমরা আমাদের বিদ্যমান Jekyll সাইটে YARD ডকুমেন্টেশন যোগ করব। Jekyll YARD-র জেনারেট করা স্ট্যাটিক ফাইলস একটি পাথে যেমন /dev-এ পাবলিশ করতে পারে। আপনি YARD আলাদাও ব্যবহার করতে পারেন আপনার ডকুমেন্টেশন সাইট তৈরি করতে।

রেইলস যখন একটি অ্যাপ জেনারেট করে, সেটি কিছু বেসিক কোড কমেন্টও জেনারেট করে:

# 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 কমান্ড রান করুন:

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

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

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

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

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

এই পয়েন্টে, মেইন Jekyll সাইট থেকে এই ডেভেলপার ডক্সে নেভিগেট করার কোনো উপায় নেই। Jekyll সাইট থেকে ডেভেলপার ডক্সে একটি লিংক যোগ করতে, docs/_config.yml-এ নিচের কন্টেন্ট যোগ করুন:

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

এটি Jekyll এবং YARD আলোচনার সমাপ্তি। এখন যেহেতু আপনার ডক্স সাইট সেট আপ হয়েছে, ডেভেলপাররা এবং রাইটাররা সিম্পলি Markdown ফাইলে (বা কোড কমেন্টে) কন্টেন্ট লিখে GitHub-এ পুশ করতে পারেন। পরের সেকশন ব্যাখ্যা করে কীভাবে এই ডক্স কন্টিনিউয়াস পাবলিকেশন দিয়ে ডিপ্লয় করতে হয়।

Netlify দিয়ে কন্টিনিউয়াস পাবলিকেশন এবং ডিপ্লয়মেন্ট

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

আমরা যা তৈরি করছি সেটি Netlify হোস্ট করছে: Docs Site।

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

স্যাম্পল অ্যাপে project-bot অ্যাপ GitHub Project-এ ডেমো দেখুন।

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

এই সেকশন ডকুমেন্টেশন তৈরী আরও ডিটেইলে আউटलাইন করে, ড্রাফ্টিং থেকে পাবলিকেশন পর্যন্ত।

ডক্স লেখা এবং রিভাইজ

আপনার এডিটোরিয়াল ওয়ার্কফ্লোর প্রথম ধাপ হলো কিছু ডক্স লিখা। ডকুমেন্টেশন লিখার টিপসের জন্য, Write the Docs-এর A Beginner's Guide to Writing Documentation দেখুন।

উদাহরণস্বরূপ, আপনার রেইলস ব্লগ অ্যাপ সম্পর্কে একটি আর্টিকেল তৈরি করতে, আপনার Jekyll docs ডিরেক্টরিতে blog-posts.md নামে একটি নতুন Markdown ফাইল তৈরি করুন:

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

যখন আপনি কোড লিখেন, আপনি সিনট্যাক্স চেক করছেন probable সিনট্যাক্স হাইলাইটার এবং কোড লিন্টার ব্যবহার করে। যদি আপনি আপনার ডক্স কোড এডিটরে লিখেন, আপনি সিমিলার লিন্টারস ব্যবহার করতে পারেন যা আপনার লেখার সময় স্পেলিং এরর এবং গ্রামার সমস্যা চেক করে। এমন লিন্টারসও আছে যা আপনার Markdown ফরম্যাটিং চেক করে।

উদাহরণস্বরূপ, VSCode আপনাকে Markdown ফাইল এডিটরে সরাসরি প্রিভিউ করতে দেয়, এবং এটিতে Markdownlint লিন্টারের এক্সটেনশন আছে, যা আপনার Markdown সিনট্যাক্সে এরর চেক করে।

একটি জনপ্রিয় প্রোজ লিন্টার আছে Vale, যেটির VSCode এবং অন্যান্য এডিটরে এক্সটেনশন রয়েছে।

আপনার কোড এডিটরে Markdown লিখার আরেকটি বোনাস হলো আপনাকে ডক্স এবং কোড লিখার জন্য এডিটর সوییচ করতে হয় না। আপনার ডক্স আপনার রেইলস অ্যাপের সাথে একই ডিরেক্টরিতে থাকার কারণে, আপনি একটি স্প্লিট লেআউট ব্যবহার করতে পারেন ডকুমেন্টেশন লিখতে কোড দেখার সময়।

চেঞ্জ কমিট

আপনি 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 এবং সাদৃশ টুলস আপনাকে আপনার ফাইলগুলোর চেঞ্জ হিস্টরি দেখতে দেয়, যার মধ্যে কী চেঞ্জ হয়েছে, চেঞ্জ কখন হয়েছে, এবং কে করা।

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

• Vale action
• Markdownlint action

এই একশনগুলো আপনার Markdown ফাইলস বিভিন্ন স্পেলিং এবং সিনট্যাক্স এরর চেক করবে আপনার ডক্সে চেঞ্জগুলো লাইভ হওয়ার আগে:

Details-এ ক্লিক করুন কেন একটি চেক পাস করছে না সেটি দেখতে:

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

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

যদি আপনার GitHub Pro, Team, বা Enterprise একাউন্ট থাকে, আপনি ব্রাঞ্চ প্রোটেকশন রুল তৈরি করতে পারেন। এই রুলস ইউজারদের চেঞ্জ মার্জ করতে বাধা দেয় যদি নির্দিষ্ট রিকোয়ারমেন্ট মিট না হয়, যেমন পাসিং স্ট্যাটাস চেক বা কমপক্ষে একজন টিম মেম্বার থেকে অনুমোদন।

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

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

উপসংহার

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

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

আরও পড়ার জন্য, GitLab-এর ডকুমেন্টেশন প্রসেস চেক আউট করুন, যেটি আপনার নিজের ডেভেলপ করার স্টার্টিং পয়েন্ট হিসেবে ব্যবহার করা যায়। তাদের Documentation Guidelinesও অনুপ্রেরণা দিতে পারে।