การสร้างเวิร์กโฟลว์เอกสารใน Rails

เวิร์กโฟลว์เอกสารสมัยใหม่มีความเกี่ยวพันกับเวิร์กโฟลว์การพัฒนาซอฟต์แวร์มากขึ้น คุณอาจติดตามปัญหาด้านเอกสารใน GitHub หรือ Jira หรือคุณอาจเขียนเอกสารในความคิดเห็นเกี่ยวกับโค้ดหรือไฟล์ Markdown นักพัฒนาในทีมของคุณอาจทำงานโดยตรงกับนักเขียนทางเทคนิค หรืออาจกำลังเขียนเอกสารโดยอิสระ เอกสารมักถูกเก็บไว้ในที่เก็บโค้ด ทดสอบคุณภาพโดยใช้ linters และเผยแพร่อย่างต่อเนื่องบนไซต์แบบคงที่ เมื่อเร็ว ๆ นี้ นักเขียนด้านเทคนิคได้สร้างคำว่า docs-like-code หรือ docs-as-code เพื่ออธิบายเวิร์กโฟลว์ประเภทนี้

Docs-as-code ถูกกำหนดโดยระบบอัตโนมัติ โดยเกี่ยวข้องกับการสร้าง อัปเดต ตรวจสอบ และอนุมัติเอกสารโดยใช้เครื่องมือการพัฒนาที่คุ้นเคย:

• ตัวติดตามปัญหา
• เครื่องมือควบคุมเวอร์ชัน
• ไฟล์ข้อความธรรมดา
• ตัวแก้ไขข้อความและโค้ด
• ตัวสร้างไซต์คงที่
• เผยแพร่อย่างต่อเนื่อง

เอกสารสามารถเก็บไว้ในที่เก็บเดียวกันกับโค้ดที่เกี่ยวข้อง ทำให้ง่ายต่อการตรวจสอบให้แน่ใจว่าเอกสารได้รับการอัปเดตควบคู่ไปกับโค้ด

เวิร์กโฟลว์นี้มีความยืดหยุ่นและสามารถปรับให้เข้ากับเครื่องมือและวิธีการต่างๆ เพื่อจุดประสงค์ในการอธิบายประกอบ บทช่วยสอนนี้พัฒนาเวิร์กโฟลว์ docs-as-code สำหรับแอป Rails โดยใช้เครื่องมือที่ใช้ Ruby เช่น Jekyll เอกสารจะถูกเก็บไว้ข้างแอปใน 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 . คุณควรเห็นรายการโพสต์ว่างและลิงก์สำหรับสร้างโพสต์ใหม่

การสร้างกลยุทธ์เนื้อหา

การวางแผนเป็นขั้นตอนแรกในการพัฒนาเวิร์กโฟลว์เอกสาร เช่นเดียวกับซอฟต์แวร์ แผนสำหรับเอกสารของคุณควรมีกลยุทธ์ด้านเนื้อหา ซึ่งจะกำหนดหัวข้อที่จำเป็นต้องจัดทำเป็นเอกสารและวิธีการ

ในการเริ่มพัฒนากลยุทธ์เนื้อหา ให้ตอบคำถามต่อไปนี้:

• กลุ่มเป้าหมายของคุณคือใคร?
  • พวกเขาเป็นนักพัฒนา ผู้ใช้ทางเทคนิคน้อยกว่า หรือทั้งสองอย่าง
  • อนุญาตให้มีส่วนร่วมในรหัสหรือเอกสารของคุณหรือไม่
  • เป็นข้อมูลภายในหรือภายนอกบริษัทของคุณหรือทั้งสองอย่าง
• ผู้ใช้พยายามทำอะไรให้สำเร็จ
• ผู้ใช้พยายามแก้ปัญหาอะไรจากการปรึกษาเอกสารของคุณ
• ผู้ใช้จะปรึกษาเอกสารของคุณอย่างไร?
  • อ่านฉันอย่างง่ายจะเพียงพอหรือไม่
  • ผู้ใช้จะต้องได้รับอนุญาตพิเศษในการเข้าถึงเอกสารหรือไม่

ตัวอย่างเช่น สมมติว่าคุณมีแอป Rails ที่มี API ประกอบ สำหรับลูกค้า คุณอาจต้องการพัฒนาคู่มือผู้ใช้แบบสาธารณะสำหรับคุณลักษณะ UI ทั้งหมดของคุณ เรื่องราวของผู้ใช้อาจเป็น "ในฐานะผู้ใช้ ฉันต้องการสร้างบล็อกโพสต์"

คุณยังสามารถสร้างเอกสารอ้างอิงสำหรับนักพัฒนาได้อีกด้วย เรื่องราวของนักพัฒนาซอฟต์แวร์อาจเป็น "ในฐานะนักพัฒนา ฉันต้องการดึงข้อมูลบล็อกโพสต์ทั้งหมดของผู้ใช้รายใดรายหนึ่ง"

คุณสามารถใช้ตัวสร้างไซต์แบบคงที่ เช่น Jekyll หรือ WordPress เพื่อนำเสนอเอกสารของผู้ใช้ในสภาพแวดล้อมที่มีแบรนด์และเป็นมิตรกับผู้ใช้ สำหรับนักพัฒนาภายในของคุณ ไซต์ที่สร้างโดย YARD แบบง่ายอาจเพียงพอ บทแนะนำนี้จะแสดงตัวอย่างให้คุณเห็นทั้งสองอย่าง

เอกสารประกอบยังสามารถรวมเข้ากับเวิร์กโฟลว์ปัจจุบันของคุณได้ ตัวอย่างเช่น หากทีมของคุณเขียนโค้ดในระยะเวลา 2 สัปดาห์ ให้พิจารณาจัดการเอกสารของคุณในกำหนดการเดียวกัน

คุณยังสามารถติดตามปัญหาด้านเอกสารควบคู่ไปกับปัญหาด้านรหัส สร้างปัญหาสำหรับคุณลักษณะหรือจุดบกพร่องของเอกสารทุกรายการ คุณลักษณะจะเป็นบทความหรือส่วนใหม่ของเนื้อหา และจุดบกพร่องอาจเป็นข้อผิดพลาด การละเลย การพิมพ์ผิด หรือปัญหาอื่นๆ ที่ต้องแก้ไข

การรวบรวมความคิดเห็นเป็นส่วนสำคัญของกลยุทธ์เนื้อหา ลองเพิ่มวิธีให้ผู้ใช้ติดต่อคุณเพื่อแจ้งความคิดเห็นเกี่ยวกับหน้าเอกสารทุกหน้าหรือสนับสนุนเอกสารผ่าน GitHub คำติชม ปุ่มมักจะเป็นเพียงแบบฟอร์มที่ส่งไปยังที่อยู่อีเมลของบริษัท บุคคลที่ได้รับมอบหมายงานนี้สามารถนำข้อเสนอแนะแต่ละรายการและเปลี่ยนเป็นปัญหา Jira หรือ GitHub เพื่อตรวจสอบและนำไปใช้ได้

เพื่อให้แน่ใจว่าสไตล์ที่สอดคล้องกันและการใช้คำศัพท์ที่แม่นยำ ให้สร้างคู่มือสไตล์บริษัทหรือทำตามที่มีอยู่ ต่อไปนี้คือตัวอย่างบางส่วนของคู่มือรูปแบบเอกสารที่จะใช้ได้กับโครงการซอฟต์แวร์ส่วนใหญ่:

• คู่มือรูปแบบเอกสารสำหรับนักพัฒนาซอฟต์แวร์ของ Google
• คู่มือสไตล์เอกสาร GitLab
• คู่มือสไตล์การเขียนของ Microsoft

ต่อไปนี้คือการอ่านเพิ่มเติมเกี่ยวกับกลยุทธ์เนื้อหาเพื่อช่วยคุณในการเริ่มต้น:

• กลยุทธ์เนื้อหา DX พร้อมพอร์ทัลนักพัฒนา
• กลยุทธ์เนื้อหาเบื้องต้นเกี่ยวกับเอกสาร

การสร้างไซต์เอกสาร

จากกลยุทธ์เนื้อหาของคุณ คุณสามารถกำหนดได้ว่าเอกสารของคุณจะถูกนำเสนอต่อผู้ชมเป้าหมายอย่างไร การกำหนดว่า ใคร จะเขียนเอกสารของคุณจะช่วยแจ้งการตัดสินใจนี้ด้วย ตัวอย่างเช่น หากนักพัฒนาและผู้มีส่วนร่วมจะเขียนเอกสารในความคิดเห็นเกี่ยวกับโค้ด คุณสามารถใช้ RDoc หรือ YARD เพื่อสร้างไซต์เอกสารแบบคงที่อย่างง่ายจากความคิดเห็นเหล่านี้ หากเอกสารของผู้ใช้จะถูกเขียนในไฟล์ Markdown ตัวสร้างไซต์แบบคงที่ เช่น Jekyll จะเป็นตัวเลือกที่ดีกว่าสำหรับการเผยแพร่เอกสารของคุณ แน่นอน คุณยังสามารถสร้างเว็บไซต์ตั้งแต่เริ่มต้นซึ่งเหมาะสำหรับทีมและโครงการของคุณ

บทความนี้ใช้ Jekyll และ YARD เพื่อแสดงเว็บไซต์เอกสารทั้งสองประเภทสำหรับแอป Rails โปรดทราบว่า Jekyll เป็นแบบ Ruby และรวมเข้ากับแอป Rails ได้ดี

เจคิลล์

จุดประสงค์ของ Jekyll คือการแปลงข้อความธรรมดาให้เป็นเว็บไซต์แบบคงที่ Jekyll สร้าง _site โฟลเดอร์ที่มีไฟล์ไซต์แบบสแตติกที่สามารถเผยแพร่โดยบริการโฮสติ้งใดก็ได้ การส่งไฟล์เหล่านี้ไปที่ GitHub หมายความว่าคุณสามารถใช้เครื่องมือเผยแพร่อย่างต่อเนื่อง เช่น Netlify เพื่อเผยแพร่เอกสารของคุณ

เวิร์กโฟลว์ที่ง่ายที่สุดกับ Jekyll เกี่ยวข้องกับการเขียนเอกสารในไฟล์ Markdown และส่งต่อไปยัง GitHub หากคุณใช้ Netlify โปรแกรมจะปรับใช้ไซต์โดยอัตโนมัติเมื่อคุณรวมการเปลี่ยนแปลงเหล่านี้กับที่เก็บ กระบวนการนี้มีรายละเอียดเพิ่มเติมในหัวข้อถัดไป

ในการสร้างไซต์ Jekyll ให้ติดตั้ง Jekyll และ Bundler จากไดเรกทอรีรากของแอป Rails ของคุณ (เช่น /blog ):

gem install jekyll bundler

การสร้างไซต์ Jekyll และเรียกใช้จากเซิร์ฟเวอร์การพัฒนาในพื้นที่ต้องการเพียงสามคำสั่ง:

jekyll new docs
cd docs
bundle exec jekyll serve

สิ่งนี้จะสร้าง /docs ไดเร็กทอรีที่มีไซต์ Jekyll น้อยที่สุด (ค่าเริ่มต้นคือธีมบล็อกที่เรียกว่า Minima) คุณสามารถใช้สิ่งนี้เป็นฐานสำหรับไซต์ Jekyll docs แบบกำหนดเองของคุณ หรือคุณสามารถติดตั้งธีมเอกสาร เช่น just-the-docs ซึ่งมาพร้อมกับการนำทางในแถบด้านข้างและฟังก์ชันการค้นหาไซต์

บทแนะนำนี้จะใช้ just-the-docs ธีม. ในการติดตั้ง ให้เรียกใช้สิ่งต่อไปนี้จาก /docs ไดเรกทอรี:

bundle add just-the-docs

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

ต่อไป เพิ่มธีมนี้ใน _config.yml ของ Jekyll ไฟล์. คุณยังสามารถปรับแต่งชื่อและคำอธิบายของไซต์ของคุณได้ในขณะที่อยู่ที่นี่:

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

เริ่มเซิร์ฟเวอร์อีกครั้ง และคุณจะเห็นไซต์เอกสารส่วนใหญ่ว่างเปล่า:

ตรวจสอบเอกสารของธีม 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!

เริ่มเซิร์ฟเวอร์อีกครั้งเพื่อดูตัวอย่างเอกสารใหม่ของคุณ:

ตอนนี้คุณมีไซต์ Jekyll พื้นฐานใน /docs โฟลเดอร์ในไดเร็กทอรีแอป Rails ของคุณ! ดูเอกสาร Jekyll เพื่อขอความช่วยเหลือในการปรับแต่งธีม Jekyll หรือเขียนธีมของคุณเอง

ลาน

ตัวสร้างเอกสาร เช่น Rdoc และ YARD สร้างเอกสารสำหรับนักพัฒนาจากความคิดเห็นของโค้ด คุณสามารถสร้างไซต์เอกสารแบบสแตนด์อโลนได้โดยใช้ YARD ซึ่งยอมรับ Rdoc และไวยากรณ์อื่นๆ ในตัวอย่างนี้ เราจะเพิ่มเอกสาร YARD ลงในไซต์ Jekyll ที่มีอยู่ของเรา 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

  # code omitted

end

หากต้องการดูว่า YARD ใช้ความคิดเห็นเหล่านี้เพื่อสร้างไซต์เอกสารอย่างไร ให้เรียกใช้ yard doc หรือ yardoc คำสั่งจากไดเร็กทอรีรูทของแอป Rails ของคุณ:

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

ถ้า yardoc คำสั่งใช้งานไม่ได้ ติดตั้ง YARD gem ด้วย 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 ที่มีแอป Rails ของคุณ

ใช้การตั้งค่าต่อไปนี้:

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 ของคุณแทนที่จะเป็นแอป Rails

เมื่อ 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 แต่คอลัมน์สามารถเชื่อมโยงโดยตรงกับปัญหาและดึงคำขอได้

ตัวอย่างเช่น ใช้เทมเพลต "คัมบังอัตโนมัติพร้อมบทวิจารณ์" เพื่อเพิ่มปัญหาใหม่และคำขอดึงลงในบอร์ดโดยอัตโนมัติ เมื่อผู้ตรวจทานเริ่มการตรวจทานหรืออนุมัติคำขอดึง บัตรปัญหาจะย้ายไปที่คอลัมน์ถัดไป วิธีนี้ช่วยให้คุณติดตามปัญหาที่กำลังดำเนินการอยู่และจุดที่ปัญหาอยู่ในขั้นตอนบรรณาธิการ

สำหรับโครงการขนาดใหญ่ที่มีมากกว่าแค่เอกสาร ให้ใช้ project-bot GitHub App เพื่อตั้งค่ากฎการทำงานอัตโนมัติ ตัวอย่างเช่น การเพิ่มป้ายกำกับเฉพาะหรือการกำหนดผู้ตรวจสอบเฉพาะจะทำให้บัตรเคลื่อนที่โดยอัตโนมัติ อีกวิธีหนึ่ง คุณสามารถรวมการจัดการเอกสารเข้ากับเวิร์กโฟลว์การจัดการโครงการที่ใหญ่ขึ้นโดยใช้เครื่องมืออย่าง Jira

ดูตัวอย่างแอปสำหรับการสาธิต project-bot แอปในโครงการ GitHub

การสร้างเอกสาร

ส่วนนี้สรุปการสร้างเอกสารโดยละเอียดยิ่งขึ้น ตั้งแต่การร่างไปจนถึงการตีพิมพ์

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

ขั้นตอนแรกในเวิร์กโฟลว์ด้านบรรณาธิการของคุณคือการเขียนเอกสาร สำหรับเคล็ดลับในการเขียนเอกสาร โปรดดูที่ A Beginner's Guide to Writing Documentation from Write the Docs

ตัวอย่างเช่น หากต้องการสร้างบทความเกี่ยวกับแอปบล็อก Rails ให้สร้างไฟล์ Markdown ใหม่ชื่อ blog-posts.md ใน docsของ Jekyll ของคุณ ไดเรกทอรี:

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

## Creating a Blog Post

...

เมื่อคุณเขียนโค้ด คุณอาจกำลังตรวจสอบไวยากรณ์ขณะที่คุณเขียนโดยใช้ตัวเน้นไวยากรณ์และตัวคั่นโค้ด หากคุณเขียนเอกสารในตัวแก้ไขโค้ด คุณสามารถใช้ Linters ที่คล้ายกันเพื่อตรวจหาข้อผิดพลาดในการสะกดคำและปัญหาด้านไวยากรณ์ขณะเขียน นอกจากนี้ยังมี linters ที่จะตรวจสอบการจัดรูปแบบ Markdown ของคุณ

ตัวอย่างเช่น VSCode ให้คุณดูตัวอย่างไฟล์ Markdown ได้โดยตรงในตัวแก้ไข และมีส่วนขยายสำหรับ Markdownlint linter ซึ่งจะตรวจสอบข้อผิดพลาดในไวยากรณ์ 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

ส่งคำสั่งนี้ไปที่ docs/blog-post สาขาในที่เก็บ GitHub ระยะไกล

สุดท้าย บน GitHub ให้สร้างคำขอดึงระหว่างสาขาใหม่ของคุณกับสาขาหลัก (หรือสาขาหลัก) คำขอดึงนี้ทำให้การเปลี่ยนแปลงของคุณได้รับการตรวจสอบและอนุมัติเช่นเดียวกับโค้ดอื่นๆ ในโครงการ

กำลังตรวจสอบและอนุมัติเอกสาร

การรวมการเปลี่ยนแปลงเอกสารกับที่เก็บอาจเป็นอันตรายได้เช่นเดียวกับในการพัฒนาซอฟต์แวร์ คุณกำลังปรับใช้การเปลี่ยนแปลงในเอกสารประกอบที่ลูกค้าและผู้ใช้ของคุณไว้วางใจ ดังนั้นคุณจะต้องแน่ใจว่ากระบวนการตรวจสอบมีความเข้มงวด เป็นความคิดที่ดีที่จะมีผู้ตรวจสอบหลายคนที่เกี่ยวข้อง รวมถึงนักพัฒนา ผู้จัดการผลิตภัณฑ์ นักเขียนด้านเทคนิค และบรรณาธิการ

ติดตามการเปลี่ยนแปลงที่ทุกคนทำกับไฟล์ และหารือเกี่ยวกับการแก้ไขเพิ่มเติมที่จำเป็น GitHub และเครื่องมือที่คล้ายกันช่วยให้คุณดูประวัติการเปลี่ยนแปลงของไฟล์ได้ รวมถึงสิ่งที่เปลี่ยนแปลง เวลาที่เปลี่ยนแปลง และใครเป็นคนทำ

คุณยังสามารถเพิ่ม GitHub Actions เพื่อตรวจสอบไฟล์ Markdown ของคุณโดยอัตโนมัติก่อนที่จะมีคนรวมเข้ากับฐานโค้ด สำหรับแต่ละ linter ที่คุณใช้ใน VSCode ให้เพิ่ม GitHub Action ที่เกี่ยวข้อง หากมี:

• การกระทำของ Vale
• การดำเนินการ Markdownlint

การดำเนินการเหล่านี้จะตรวจสอบไฟล์ Markdown ของคุณเพื่อหาข้อผิดพลาดในการสะกดและไวยากรณ์ต่างๆ ก่อนที่การเปลี่ยนแปลงในเอกสารของคุณจะมีผล:

คลิก รายละเอียด เพื่อดูว่าทำไมเช็คไม่ผ่าน:

หากต้องการเพิ่ม Vale และ Markdownlint ลงในการตรวจสอบคำขอดึง ให้คัดลอกไฟล์เวิร์กโฟลว์ docs.yml จากที่เก็บตัวอย่าง

เพื่อให้การดำเนินการ Vale ทำงานได้ คุณอาจต้องสร้าง .github/styles/vocab.txt ไฟล์ในที่เก็บของคุณ นี่คือรายการคำ (หนึ่งคำต่อบรรทัด) ที่ Vale จะไม่สนใจ เช่น ชื่อบริษัทของคุณหรือชื่อคนในทีมของคุณ

หากคุณมีบัญชี GitHub Pro, Team หรือ Enterprise คุณสามารถสร้างกฎการป้องกันสาขาได้ กฎเหล่านี้ป้องกันไม่ให้ผู้ใช้รวมการเปลี่ยนแปลงเว้นแต่จะเป็นไปตามข้อกำหนดบางอย่าง เช่น ผ่านการตรวจสอบสถานะหรือได้รับการอนุมัติจากสมาชิกในทีมอย่างน้อยหนึ่งคน

โปรดจำไว้ว่า Netlify ยังแสดงตัวอย่างไซต์ของคุณในรายการตรวจสอบ ดังนั้นผู้ตรวจทานจึงสามารถตรวจสอบได้ว่าทุกอย่างดูดี ก่อน รวมการเปลี่ยนแปลงและปรับใช้ไซต์อีกครั้ง

หลังจากที่คุณได้ตรวจสอบอย่างละเอียดและรวมการเปลี่ยนแปลงในเอกสารของคุณแล้ว Netlify จะทำให้ไซต์ของคุณใช้งานได้อีกครั้ง ไปที่ไซต์ Jekyll สดของคุณเพื่อดูการเปลี่ยนแปลง

บทสรุป

ตอนนี้คุณควรมีเวิร์กโฟลว์เอกสารพื้นฐานใน GitHub สำหรับแอป Rails หรือโครงการอื่นๆ การจัดการเอกสารอย่างโค้ดสามารถทำได้ง่ายหรือซับซ้อนตามที่ควรจะเป็น สำหรับโครงการขนาดเล็ก ระบบอัตโนมัติเล็กน้อยใน GitHub อาจเป็นสิ่งที่คุณต้องการ โครงการขนาดใหญ่อาจรวมเข้ากับแผนกและทีมอื่นๆ อย่างใกล้ชิดมากขึ้น และด้วยเหตุนี้จึงรวมเข้ากับเครื่องมืออื่นๆ

อย่าลืมดูตัวอย่างที่เก็บ GitHub สำหรับแอป Rails และตัวอย่างไซต์ Jekyll ที่เราสร้างในบทความนี้ repo ประกอบด้วยปัญหาตัวอย่างและคำขอดึงตลอดจนป้ายกำกับ นอกจากนี้ยังมีโปรเจ็กต์ GitHub แบบอัตโนมัติและเทมเพลตคำขอดึงตัวอย่างสำหรับผู้เขียน ผู้ตรวจสอบ และผู้ดูแลที่ต้องปฏิบัติตามเมื่อเพิ่มเอกสารลงในฐานโค้ด

สำหรับการอ่านเพิ่มเติม โปรดดูที่กระบวนการเอกสารของ GitLab ซึ่งสามารถใช้เป็นจุดเริ่มต้นสำหรับการพัฒนาของคุณเอง หลักเกณฑ์ด้านเอกสารอาจให้แรงบันดาลใจด้วย