การออกแบบ Documentation Workflow ที่มีประสิทธิภาพสำหรับ Rails Projects

Documentation workflows สมัยใหม่กำลังผูกมัดกับ software development workflow มากขึ้น คุณอาจ track documentation issues ใน GitHub หรือ Jira หรือเขียน docs ใน code comments หรือ Markdown files นักพัฒนาในทีมอาจทำงานกับ technical writers โดยตรง หรือเขียน docs แยกกัน Docs บ่อยครั้งเก็บใน code repositories ทดสอบคุณภาพด้วย linters และ publish ตลอดบน static sites Technical writers ได้สร้างคำว่า docs-like-code หรือ docs-as-code เพื่ออธิบาย workflow ประเภทนี้

Docs-as-code ถูกกำหนดโดย automation มันเกี่ยวข้องกับการสร้าง อัปเดต review และ approve documentation โดยใช้ development tools ที่คุ้นเคย:

• Issue trackers
• Version control tools
• Plain-text files
• Text และ code editors
• Static site generators
• Continuous publication

Docs สามารถเก็บใน repositories เดียวกับ code ที่เกี่ยวข้อง ทำให้ง่ายต่อการ ensure docs ถูกอัปเดตพร้อมกับ code เอง

Workflow นี้ยืดหยุ่นและปรับตัวได้กับหลาย combination ของ tools และ methodologies เพื่อการillustration บทช่วยสอนนี้พัฒนา docs-as-code workflow สำหรับ Rails app โดยใช้ Ruby-based tools เช่น Jekyll Docs ถูกเก็บพร้อมกับ app ใน GitHub และจัดการด้วย GitHub issues, labels, projects และ pull request reviews ตัวอย่างนี้ illustrate docs-as-code principles ที่ปรับใช้กับ tools อื่นและ integrate เข้ากับ workflows อื่นได้

Prerequisites (ข้อกำหนดเบื้องต้น)

คู่มือนี้สำหรับนักพัฒนา คุณควรคุ้นเคยกับ tools ต่อไปนี้: Git, code editors และ Markdown บทความนี้อธิบายวิธีใช้ tools เหล่านี้สร้าง documentation workflow

ประกอบกับบทความนี้มี live sample site โฮสต์โดย Netlify และ sample GitHub repository

เพื่อติดตามบทความนี้ สร้าง simple blog application ใน Rails ด้วยคำสั่งน้อยๆ:

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

ใน config/routes.rb สร้าง index page:

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

สุดท้าย รัน database migration และเริ่ม Rails server เพื่อตรวจสอบว่าทุกอย่างทำงาน:

rails db:migrate rails s 

ไปที่ localhost:3000 คุณควรเห็น empty list of posts และ link สร้าง post ใหม่

การสร้าง Content Strategy

การวางแผนเป็นขั้นตอนแรกในการพัฒนา documentation workflow เหมือนกับ software development แผนสำหรับ docs ควรมี content strategy ซึ่งกำหนดว่าจะต้อง document หัวข้อไหนและอย่างไร

เพื่อเริ่มพัฒนา content strategy ตอบคำถามต่อไปนี้:

• Intended audience คือใคร?
  • เป็น developers, less technical users หรือทั้งคู่?
  • ได้รับอนุญาตให้ contribute code หรือ docs หรือไม่?
  • เป็น internal หรือ external ของบริษัท หรือทั้งคู่?
• Users พยายามทำอะไร?
• Users พยายามแก้ปัญหาอะไรโดยอ้างอิง docs ของคุณ?
• Users จะ consult docs ของคุณอย่างไร?
  • README เรียบง่ายเพียงพอหรือไม่?
  • Users ต้องการ special permission เพื่อเข้าถึง documentation หรือไม่?

ตัวอย่าง 想像ว่าคุณมี Rails app พร้อม API สำหรับลูกค้า คุณอาจต้องการพัฒนา public user guide สำหรับ UI features ทั้งหมด User story อาจเป็น "As a user, I want to create a blog post."

คุณอาจสร้าง reference documentation สำหรับนักพัฒนา Developer story อาจเป็น "As a developer, I want to retrieve all the blog posts of a specific user."

คุณสามารถใช้ static site generator เช่น Jekyll หรือ WordPress เพื่อนำเสนอ user docs ในสภาพแวดล้อมที่ branded และ user-friendly สำหรับ internal developers YARD-generated site แบบง่ายอาจเพียงพอ บทช่วยสอนนี้จะแสดงตัวอย่างทั้งสองแบบ

Documentation ยังสามารถ integrate เข้ากับ workflow ปัจจุบันได้ ตัวอย่าง หากทีมเขียน code ใน 2-week sprints พิจารณาจัดการ documentation บน schedule เดียวกัน

คุณยังสามารถ track documentation issues พร้อมกับ code issues สร้าง issue สำหรับทุก docs feature หรือ bug Feature จะเป็นบทความใหม่หรือ section ใหม่ของ content Bug จะเป็น error, omission, typo หรือ issue อื่นที่ต้องการ fix

การรวบรวม feedback เป็นส่วนสำคัญของ content strategy พิจารณาเพิ่มวิธีให้ users ติดต่อส่ง feedback บนทุก doc page หรือ contribute docs ผ่าน GitHub ปุ่ม Feedback ปกติเป็นแค่ form ส่งไปที่ company email ผู้ที่ได้รับมอบหมายงานนี้จะนำแต่ละ feedback item ไปทำเป็น Jira หรือ GitHub issue เพื่อ review และ implement

เพื่อให้ได้ consistent style และ precise terminology สร้าง company style guide หรือ follow existing one นี่คือตัวอย่าง documentation style guides ที่ทำงานได้กับ software projects ส่วนใหญ่:

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

อ่านเพิ่มเติมเกี่ยว content strategy เพื่อเริ่มต้น:

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

การสร้าง Docs Site

จาก content strategy คุณสามารถกำหนดได้ว่า docs จะถูกนำเสนอให้ intended audience อย่างไร การกำหนด ใคร จะเขียน docs จะช่วยตัดสินใจนี้ด้วย ตัวอย่าง หาก developers และ contributors จะเขียน documentation ใน code comments RDoc หรือ YARD สามารถใช้สร้าง simple static docs site จาก comments เหล่านี้ หาก user documentation จะเขียนใน Markdown files static site generator เช่น Jekyll จะเป็นตัวเลือกที่ดีกว่าสำหรับ publish docs อย่างไรก็ตาม คุณก็สามารถสร้าง site from scratch ที่ทำงานได้สำหรับทีมและโปรเจกต์ของคุณ

บทความนี้ใช้ Jekyll และ YARD เพื่อ illustrate ทั้งสองประเภทของ documentation sites สำหรับ Rails app โปรดทราบว่า Jekyll เป็น Ruby-based และ integrate เข้ากับ Rails app ได้ดี

Jekyll

วัตถุประสงค์ของ Jekyll คือแปลง plain text เป็น static website Jekyll สร้างโฟลเดอร์ _site ที่มี static site files ที่ publish ได้โดย hosting service ใดๆ การ push files เหล่านี้ไป GitHub หมายความว่าคุณสามารถใช้ continuous publication tools เช่น Netlify เพื่อ publish docs กระบวนการนี้อธิบายรายละเอียดในส่วนถัดไป

เพื่อสร้าง Jekyll site ติดตั้ง Jekyll และ Bundler จาก root directory ของ Rails app (เช่น /blog):

gem install jekyll bundler 

การสร้าง Jekyll site และรันจาก local development server ต้องใช้เพียงสามคำสั่ง:

jekyll new docs cd docs bundle exec jekyll serve 

นี่สร้าง directory /docs ที่มี minimal Jekyll site (default คือ blog theme ชื่อ Minima) คุณสามารถใช้เป็น base สำหรับ custom Jekyll docs site ของคุณ หรือคุณสามารถติดตั้ง docs theme เช่น just-the-docs ซึ่งมาพร้อม sidebar navigation และ site search functionality

บทช่วยสอนนี้จะใช้ theme just-the-docs เพื่อติดตั้ง ให้รันคำสั่งต่อไปนี้จาก directory /docs:

bundle add just-the-docs 

ลบ theme minima ออกจาก Gemfile เนื่องจากเป็น default theme ที่คุณจะไม่ใช้แล้ว คุณยังสามารถลบ directory posts ได้

ต่อไป เพิ่ม theme นี้ใน _config.yml ของ Jekyll คุณยังสามารถ customize title และ description ของ site ได้ในขณะนี้:

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 

เริ่ม server อีกครั้ง และคุณจะเห็น docs site ว่างส่วนใหญ่:

ตรวจสอบ documentation ของ Jekyll theme ของคุณว่า directory ไหนควรเก็บ Markdown files สำหรับ just-the-docs Markdown files สามารถอยู่ใน root directory ซึ่งตรงกับ base path ของ site สร้าง Markdown file ใหม่ใน root directory เพื่อดูการทำงาน:

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

เริ่ม server อีกครั้งเพื่อดู sample doc ใหม่:

ตอนนี้คุณมี basic Jekyll site ในโฟลเดอร์ /docs ใน Rails app directory แล้ว! ดู Jekyll docs เพื่อช่วย customize Jekyll theme หรือเขียน theme เอง

YARD

Documentation generators เช่น Rdoc และ YARD สร้าง developer documentation จาก code comments คุณสามารถสร้าง standalone docs site ด้วย YARD ซึ่งยอมรับ Rdoc และ syntax อื่นๆ ในตัวอย่างนี้ เราจะเพิ่ม YARD documentation เข้าไปใน Jekyll site ที่มีอยู่ Jekyll สามารถ publish static files ที่ YARD สร้างได้ที่ path เช่น /dev คุณก็สามารถใช้ YARD เพียงอย่างเดียวสร้าง documentation site ได้

เมื่อ Rails generate app มันยัง generate basic code comments ไปด้วย:

# 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 ใช้ comments เหล่านี้สร้าง docs site อย่างไร ให้รันคำสั่ง yard doc หรือ yardoc จาก root directory ของ Rails app:

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

หากคำสั่ง yardoc ไม่ทำงาน ติดตั้ง YARD gem ด้วย bundle install yard

YARD จะวาง output files ใน output-dir ซึ่งตั้งค่าเป็น Jekyll directory /docs/dev ในคำสั่งข้างต้น Jekyll ตอนนี้สามารถ publish YARD's site files ด้วย base path /dev

Documentation ที่ซับซ้อนกว่านี้สามารถสร้างได้ด้วย RDoc หรือ syntax อื่นๆ (ดู YARD documentation) แตเราจะใช้ documentation ที่มีอยู่ต่อไป

เริ่ม Jekyll server และไปที่ localhost:4000/dev เพื่อดู YARD-generated documentation:

ในจุดนี้ ไม่มีวิธี navigate ไป developer docs จาก Jekyll site หลัก เพื่อเพิ่ม link จาก Jekyll site ไป developer docs ให้เพิ่มใน docs/_config.yml:

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

จบการพูดถึง Jekyll และ YARD ตอนนี้ docs site ของคุณ setup เสร็จแล้ว developers และ writers สามารถเขียน content ใน Markdown files (หรือ code comments) และ push ไป GitHub ส่วนถัดไปอธิบายการ deploy docs ด้วย continuous publication

Continuous Publication และ Deployment ด้วย Netlify

Continuous publication สะดวกสำหรับ docs sites เพราะ live site สามารถอัปเดตอัตโนมัติเมื่อ changes ใน docs ถูก approve และ merge เข้า repository บทช่วยสอนนี้ใช้ Netlify แต่มี tools อื่น เช่น GitHub Pages, GitLab Pages และ Firebase

Site ที่เราสร้างมานี้ hosted by Netlify: Docs Site

เพื่อตั้งค่า Netlify สำหรับ docs site เริ่มด้วยการ sign up Netlify account และ connect กับ GitHub repository ที่มี Rails app

ใช้ settings ต่อไปนี้:

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

หากบาง settings ไม่พร้อมตอนสร้าง Netlify site คลิก Deploy ไปก่อน คุณสามารถ cancel แล้วกลับไป Deploy settings ตั้ง base directory เป็น docs เพื่อให้ Netlify deploy Jekyll docs site แทน Rails app

เมื่อ Netlify deploy Jekyll site เสร็จ ไปที่ live site เพื่อให้แน่ใจว่าทุกอย่างถูกต้อง

ประโยชน์ของ Netlify คือมันให้ live preview link โดยตรงจากแต่ละ pull request:

คุณสามารถตรวจสอบว่า changes จะ publish ถูกต้องก่อน merge pull request และ trigger re-deploy ของ site ส่วนถัดไปครอบคลุม workflow นี้รายละเอียด

การตั้งค่า Editorial Workflow ใน GitHub

เมื่อมี strategy สำหรับเขียน documentation และ site สำหรับ publish แล้ว คุณพร้อมเริ่มเขียน docs และ integrate เข้ากับ software workflow

Typical editorial workflow เกี่ยวข้องกับ drafting document, reviewing document และ publishing เนื่องจากคล้ายกับ software development process คุณสามารถใช้ software development tools ทำให้ process มีประสิทธิภาพมากขึ้น

นี่คือตัวอย่าง editorial workflow สำหรับทีมที่ใช้ GitHub:

1. [Writer] สร้างหรืออัปเดต file ตาม documentation feature request หรือ bug (ตามที่ระบุใน GitHub issue)
2. [Writer] Push change ไป GitHub branch
3. [Writer] เปิด pull request
4. [Reviewer] Review changes
5. [Reviewer/Maintainer] Merge changes เข้า repository ซึ่งควร trigger new build ของ docs site

GitHub จัดการ change history ของ content อัตโนมัติ ซึ่งเป็น key ใน docs-as-code workflow คุณเห็นได้ว่าอะไรเปลี่ยน ใครเปลี่ยน เมื่อไหร่เปลี่ยน และทำไมหรืออย่างไร (ถ้าระบุใน comments, discussion หรือ related issue) เก็บทั้งหมดไว้ที่เดียว สำหรับทุก member ในทีม ดูได้ตลอดเวลา

Issues และ Labels

คุณสามารถใช้ issue templates เดียวกันสำหรับ documentation ใหม่เหมือนกับ code นี่ช่วยให้ community members ขอ documentation ที่อาจขาดหายไป หรือแจ้ง team เกี่ยวกับ errors Managers ยังสามารถใช้ issues assign developers หรือ writers ให้ documentation tasks

เพื่อแยก docs issues จาก code issues คุณสามารถใช้ labels เพิ่ม label documentation เพื่อบอกว่าเกี่ยวกับ docs คุณยังสร้าง labels สำหรับ specific docs issues เช่น docs::feature หรือ docs::fix

คุณอาจเพิ่ม instructions ใน issue templates เกี่ยวกับ issue title หรือ labels ที่เหมาะสม เหมือนกับ code-related issues

Workflow labels เช่น docs::in progress และ docs::in review ก็มีประโยชน์ พวกมัน reflect สิ่งที่กำลังทำงานอยู่

ตอนกำหนด documentation process โปรดระบุว่าใครรับผิดชอบเปลี่ยน labels และเมื่อไหร่ ตัวอย่าง คนเขียน draft จะเปลี่ยน label เป็น docs::in progress เมื่อเริ่มเขียน draft เมื่อ reviewer ได้รับ draft reviewer ควรเปลี่ยน issue label เป็น docs::in review

การจัดการ Workflow

สำหรับ small teams และ projects การใช้ GitHub Projects เป็นวิธีสะดวกจัดการ editorial content โดยตรงจาก GitHub พวกมันคล้าย project management boards เช่นใน Trello แต columns สามารถ link เข้ากับ issues และ pull requests ได้โดยตรง

ตัวอย่าง ใช้ template "Automated kanban with reviews" เพื่อให้ new issues และ pull requests เพิ่มเข้า board อัตโนมัติ เมื่อ reviewer เริ่ม review หรือ approve pull request issue card จะ move ไป column ถัดไป นี่ช่วยให้คุณ track active issues และว่าอยู่ที่ไหนใน editorial process

สำหรับ larger projects ที่รวมมากกว่าแค่ docs ใช้ project-bot GitHub App ตั้งค่า automation rules ตัวอย่าง เพิ่ม specific label หรือ assign specific reviewer จะ trigger automatic card movement หรือคุณสามารถ integrate documentation management เข้ากับ project management workflow ใหญ่กว่าใช้ tool เช่น Jira

ดู sample app สำหรับ demonstration ของ project-bot app ใน GitHub Project

การสร้าง Documentation

ส่วนนี้ outline การสร้าง documentation รายละเอียด ตั้งแต่ drafting ถึง publication

การเขียนและแก้ไข Docs

ขั้นตอนแรกใน editorial workflow คือเขียน docs บ้าง สำหรับ tips การเขียน documentation ดู A Beginner's Guide to Writing Documentation from Write the Docs

ตัวอย่าง เพื่อสร้างบทความเกี่ยวกับ Rails blog app สร้าง Markdown file ใหม่ชื่อ blog-posts.md ใน Jekyll docs directory:

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

ตอนเขียนโค้ด คุณอาจ check syntax ขณะเขียนด้วย syntax highlighters และ code linters หากคุณเขียน docs ใน code editor คุณสามารถใช้ linters คล้ายกันที่ตรวจ spelling errors และ grammar problems ขณะเขียน มี linters ที่ตรวจ Markdown formatting ด้วย

ตัวอย่าง VSCode อนุญาต preview Markdown files โดยตรงใน editor และมี extension สำหรับ Markdownlint linter ซึ่งตรวจ errors ใน Markdown syntax

ยังมี prose linter ยอดนิยมชื่อ Vale ซึ่งมี extensions ใน VSCode และ editors อื่นๆ

ประโยชน์อีกอย่างของการเขียน Markdown ใน code editor คือคุณไม่ต้องสลับ editors ระหว่างเขียน docs และ code สำหรับโปรเจกต์เดียวกัน ด้วย docs เก็บใน directory เดียวกับ Rails app คุณสามารถใช้ split layout เขียน documentation พร้อมดู code

การ Commit Changes

คุณเขียน document ใหม่ใน VSCode และตรวจ spelling mistakes และ syntax errors แล้ว ขั้นตอนต่อไปคือสร้าง branch ใหม่และ commit change ไป 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 

Push commit นี้ไป branch docs/blog-post ใน remote GitHub repository

สุดท้าย บน GitHub สร้าง pull request ระหว่าง branch ใหม่และ master (หรือ main) branch Pull request นี้อนุญาตให้ changes ถูก review และ approve เหมือน code อื่นในโปรเจกต์

การ Review และ Approve Docs

การ Merge documentation changes เข้า repository อันตรายเท่ากับ software development คุณกำลัง deploy changes ไป documentation ที่ customers และ users พึ่งพา ดังนั้นคุณจะอย่าให้ review process เป็น rigorous ควรมี reviewers หลายคน รวมถึง developers, product managers, technical writers และ editors

ติดตาม changes ที่ทุกคนทำใน file และ discuss further revisions ที่จำเป็น GitHub และ tools คล้ายๆ อนุญาตให้ดู change history ของ files รวมถึงอะไรเปลี่ยน เมื่อเปลี่ยน และใครเปลี่ยน

คุณยังสามารถเพิ่ม GitHub Actions เพื่อ auto check Markdown files ก่อนที่ใครจะ merge เข้า code base สำหรับแต่ละ linter ที่ใช้ใน VSCode เพิ่ม GitHub Action ที่ตรงกันหากมี:

• Vale action
• Markdownlint action

Actions นี้จะตรวจ Markdown files หา spelling และ syntax errors ต่างๆ ก่อนที่ changes ใน docs จะไป live:

คลิก Details เพื่อดูว่า check ไหนไม่ผ่าน:

เพื่อเพิ่ม Vale และ Markdownlint ให้ pull request checks copy docs.yml workflow file จาก sample repository

สำหรับ Vale action ให้ทำงาน คุณอาจต้องสร้าง file .github/styles/vocab.txt ใน repository นี่คือรายการคำ (คำละบรรทัด) ที่ Vale จะ ignore เช่น company name หรือชื่อคนในทีม

หากคุณมี GitHub Pro, Team หรือ Enterprise account คุณสามารถสร้าง branch protection rules Rules นี้ป้องกัน users จากการ merge changes เว้นแต่ requirements บางอย่างถูกปฏิบัติ เช่น passing status checks หรือได้ approval จาก team member อย่างน้อยหนึ่งคน

จำได้ว่า Netlify ให้ preview ของ site ใน list of checks ดังนั้น reviewer สามารถตรวจสอบว่าทุกอย่างดูดี ก่อน merge changes และ re-deploy site

หลังจาก review อย่างละเอียดและ merge changes documentation แล้ว Netlify จะ re-deploy site ไปที่ live Jekyll site เพื่อดู changes

สรุป

ตอนนี้คุณควรมี basic documentation workflow ใน GitHub สำหรับ Rails app หรือโปรเจกต์อื่นๆ การจัดการ docs เหมือน code อาจง่ายหรือซับซ้อนเท่าที่ต้องการ สำหรับ small projects automation นิดหน่อยใน GitHub อาจเพียงพอ Larger projects อาจ integrate ใกล้ชิดกับ departments และ teams อื่นๆ และด้วย tools อื่นๆ

โปรดดู sample GitHub repository สำหรับ Rails app และ sample Jekyll site ที่เราสร้างในบทความนี้ Repo รวม sample issues และ pull request รวมถึง labels ยังมี automated GitHub Project และ sample pull request template สำหรับ authors, reviewers และ maintainers ตามเมื่อเพิ่ม documentation เข้า code base

สำหรับ further reading ดู documentation process ของ GitLab ซึ่งอาจใช้เป็น starting point สำหรับพัฒนาของคุณ Documentation Guidelines ของพวกเขาอาจให้แรงบันดาลใจด้วย