Quy trình tài liệu hiện đại ngày càng gắn liền với quy trình phát triển phần mềm. Bạn có thể theo dõi issue tài liệu trên GitHub hoặc Jira, hoặc viết docs trong code comments hoặc file Markdown. Developer trong team có thể làm việc trực tiếp với technical writer, hoặc viết docs độc lập. Docs thường lưu trong code repository, test chất lượng bằng linters, và publish liên tục trên static sites. Technical writers gần đây đặt thuật ngữ docs-like-code hoặc docs-as-code để mô tả loại quy trình này.
Docs-as-code được định nghĩa bởi automation. Nó liên quan đến tạo, cập nhật, review, approve tài liệu dùng công cụ phát triển quen thuộc:
- Issue trackers
- Version control tools
- Plain-text files
- Text và code editors
- Static site generators
- Continuous publication
Docs có thể lưu cùng repository với code liên quan, giúp dễ dàng đảm bảo docs cập nhật cùng code.
Quy trình này linh hoạt và thích ứng với nhiều kết hợp tools và methodologies. Để minh họa, tutorial này phát triển workflow docs-as-code cho Rails app dùng Ruby-based tools như Jekyll. Docs lưu cùng app trong GitHub và quản lý dùng GitHub issues, labels, projects, pull request reviews. Ví dụ này minh họa nguyên tắc docs-as-code có thể thích ứng tools khác và tích hợp workflow khác.
Điều Kiện Tiên Quyết
Hướng dẫn này dành cho developer. Bạn nên quen với: Git, code editors, Markdown. Bài viết mô tả cách dùng tools này tạo documentation workflow.
Kèm bài viết là sample site live, hosted by Netlify, và sample GitHub repository.
Để theo dõi bài viết, tạo simple blog app trong Rails với vài lệnh:
gem install rails
rails new blog
cd blog
rails generate scaffold Post title:string body:text
Trong config/routes.rb, tạo index page:
Rails.application.routes.draw do
resources :posts
root 'posts#index'
end
Cuối cùng, chạy migration và start Rails server kiểm tra:
rails db:migrate
rails s
Truy cập localhost:3000. Bạn nên thấy danh sách posts rỗng và link tạo post mới.
Tạo Content Strategy
Planning là bước đầu phát triển documentation workflow, giống như software. Kế hoạch docs nên bao gồm content strategy, xác định chủ đề nào cần document và như thế nào.
Để bắt đầu content strategy, trả lời các câu hỏi:
- Đối tượng độc giả là ai?
- Developer, user ít technical, hay cả hai?
- Được phép contribute code hay docs?
- Internal hay external công ty hay cả hai?
- User muốn đạt được gì?
- User cố giải quyết vấn đề gì bằng cách đọc docs?
- User sẽ consult docs như thế nào?
- Readme đơn giản có đủ không?
- Cần permission đặc biệt truy cập docs?
Ví dụ, tưởng tượng bạn có Rails app kèm API. Cho customer, có thể develop public user guide cho tất cả UI features. User story: "As a user, I want to create a blog post."
Bạn cũng có thể tạo reference documentation cho developer. Developer story: "As a developer, I want to retrieve all blog posts of a specific user."
Bạn có thể dùng static site generator như Jekyll hoặc WordPress để trình bày user docs trong môi trường branded, user-friendly. Cho internal developer, site generate bởi YARD có thể đủ. Tutorial này sẽ show cả hai.
Documentation cũng có thể tích hợp workflow hiện tại. Ví dụ, team viết code 2-week sprints, hãy quản lý documentation cùng schedule.
Bạn cũng có thể track documentation issues cùng code issues. Tạo issue cho mỗi docs feature hoặc bug. Feature là bài viết hoặc section content mới, bug là error, omission, typo, hoặc issue khác cần fix.
Thu thập feedback là phần quan trọng của content strategy. Cân nhắc thêm cách user contact feedback trên mỗi doc page hoặc contribute docs qua GitHub. Nút Feedback thường chỉ form gửi email công ty; người được assign task này sẽ biến feedback thành Jira hoặc GitHub issue để review và implement.
Để đảm bảo style nhất quán và terminology chính xác, tạo company style guide hoặc follow existing. Ví dụ documentation style guides phù hợp hầu hết software projects:
- Google Developer Documentation Style Guide
- GitLab Documentation Style Guide
- Microsoft Writing Style Guide
Đọc thêm về content strategy:
- DX Content Strategy with Developer Portals
- Primer on Documentation Content Strategy
Xây Dựng Docs Site
Từ content strategy, xác định docs sẽ trình bày như thế nào cho độc giả. Xác định ai viết docs cũng giúp quyết định này. Ví dụ, nếu developer và contributor viết docs trong code comments, RDoc hoặc YARD tạo simple static docs site từ comments. Nếu user documentation viết trong Markdown files, static site generator như Jekyll là lựa chọn tốt hơn. Tất nhiên, bạn cũng có thể tạo site từ đầu phù hợp team và project.
Bài viết dùng Jekyll và YARD minh họa cả hai loại docs site cho Rails app. Lưu ý Jekyll là Ruby-based và tích hợp tốt vào Rails app.
Jekyll
Mục đích Jekyll là biến plain text thành static website. Jekyll tạo thư mục _site chứa static site files có thể publish bởi bất kỳ hosting service nào. Push files lên GitHub nghĩa là bạn dùng continuous publication tools như Netlify để publish docs.
Quy trình đơn giản nhất với Jekyll: viết docs trong Markdown files và push lên GitHub. Nếu dùng Netlify, tự động deploy site khi merge changes vào repository. Quá trình này chi tiết hơn ở section sau.
Để tạo Jekyll site, cài Jekyll và Bundler từ root directory Rails app (ví dụ: /blog):
gem install jekyll bundler
Tạo Jekyll site và chạy từ local dev server chỉ cần ba lệnh:
jekyll new docs
cd docs
bundle exec jekyll serve
Tạo thư mục /docs chứa Jekyll site tối thiểu (default là blog theme Minima). Bạn dùng làm base cho custom Jekyll docs site. Hoặc cài docs theme như just-the-docs, có sidebar navigation và site search.
Tutorial này dùng theme just-the-docs. Để cài, chạy từ thư mục /docs:
bundle add just-the-docs
Xóa theme minima khỏi Gemfile vì nó default theme bạn không dùng nữa. Bạn cũng xóa thư mục posts.
Tiếp, thêm theme vào _config.yml Jekyll. Bạn cũng customize title và 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
Khởi động server lại, bạn sẽ thấy docs site hầu như trống:
Check docs theme documentation xem thư mục nào chứa Markdown files. Với just-the-docs, Markdown files ở root directory, tương ứng base path site. Tạo file Markdown mới ở root directory xem hoạt động:
---
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!
Khởi động server lại xem sample doc mới:
Bây giờ bạn có basic Jekyll site trong thư mục /docs trong Rails app directory! Xem Jekyll docs để customize theme hoặc viết theme riêng.
YARD
Documentation generators như Rdoc và YARD generate developer documentation từ code comments. Bạn có thể tạo standalone docs site dùng YARD, chấp nhận Rdoc và syntax khác. Ví dụ này, thêm YARD documentation vào Jekyll site hiện có. Jekyll publish static files YARD generate tại path như /dev. Bạn cũng dùng YARD riêng tạo docs site.
Khi Rails generate app, cũng generate vài code comments cơ bản:
# 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
Để xem YARD dùng comments tạo docs site, chạy yard doc hoặc yardoc từ root directory Rails app:
yardoc --output-dir docs/dev app/**/*.rb
Nếu lệnh
yardockhông chạy, cài YARD gem vớibundle install yard.
YARD đặt output files trong output-dir, set là thư mục Jekyll /docs/dev trong lệnh trên. Jekyll giờ publish site files YARD với base path /dev.
Documentation phức tạp hơn tạo được dùng RDoc hoặc syntax khác (xem YARD docs), nhưng ở đây dùng documentation hiện có.
Khởi động Jekyll server và truy cập localhost:4000/dev xem YARD-generated documentation:
Lúc này chưa có cách navigate từ Jekyll site chính sang developer docs. Để thêm link từ Jekyll site đến developer docs, thêm vào docs/_config.yml:
# Aux links for the upper right navigation
aux_links:
"Developer Documentation": - "/dev"
Đây kết thúc thảo luận Jekyll và YARD. Bây giờ docs site setup xong, developer và writer chỉ cần viết content trong Markdown files (hoặc code comments) và push lên GitHub. Section sau giải thích deploy docs với continuous publication.
Continuous Publication Và Deployment Với Netlify
Continuous publication tiện cho docs site vì live site cập nhật tự động khi changes docs approved và merged vào repository. Tutorial dùng Netlify, nhưng tools khác: GitHub Pages, GitLab Pages, Firebase.
Site chúng ta build được host bởi Netlify: Docs Site.
Để setup Netlify cho docs site, đăng ký Netlify account và connect GitHub repository chứa Rails app.
Dùng settings sau:
Repository github.com/your-username/your-rails-repo
Base directory docs
Build command jekyll build
Publish directory docs/\_site
Builds Active
Nếu một số settings chưa available khi tạo Netlify site, click Deploy trước. Sau đó cancel và quay lại Deploy settings. Set base directory
docsđảm bảo Netlify deploy Jekyll docs site chứ không phải Rails app.
Khi Netlify deploy xong Jekyll site, truy cập live site kiểm tra.
Lợi ích Netlify: cung cấp live preview link trực tiếp từ mỗi pull request:
Bạn check changes sẽ publish đúng trước khi merge pull request và trigger re-deploy site. Section sau cover workflow này chi tiết.
Thiết Lập Editorial Workflow Trong GitHub
Với strategy viết documentation và site publish, bạn sẵn sàng viết docs và tích hợp vào software workflow.
Editorial workflow điển hình: draft document, review document, publish. Writer tự review, nhưng editor, manager, stakeholder thường tham gia final review. Vì giống software development, dùng software development tools làm quy trình hiệu quả hơn.
Ví dụ editorial workflow team dùng GitHub:
- [Writer] Tạo hoặc update file theo documentation feature request hoặc bug (ghi trong GitHub issue).
- [Writer] Push change lên GitHub branch.
- [Writer] Mở pull request.
- [Reviewer] Review changes.
- [Reviewer/Maintainer] Merge changes vào repository, trigger new build docs site.
GitHub tự quản change history content, cũng key trong docs-as-code workflow. Bạn thấy gì changed, ai changed, khi changed, tại sao/cách changed (nếu mention trong comments, discussion, related issue). Lưu ở một nơi cho all team members thấy mọi lúc.
Issues Và Labels
Bạn dùng cùng issue templates cho documentation mới như code. Cho phép community request docs thiếu hoặc báo lỗi. Manager dùng issues assign developer/writer cho documentation tasks.
Để phân biệt docs issues và code issues, dùng labels. Thêm label documentation chỉ related docs. Cũng tạo labels cho specific docs issues, như docs::feature hoặc docs::fix.
Bạn có thể thêm instructions vào issue templates về issue title hoặc labels phù hợp, giống code issues.
Workflow labels như docs::in progress và docs::in review cũng hữu ích. Chúng phản ánh đang làm gì.
Khi định nghĩa documentation process, chỉ rõ ai responsible thay đổi labels và khi nào. Ví dụ, người viết draft đổi label docs::in progress khi bắt đầu. Khi reviewer nhận draft, reviewer đổi label docs::in review.
Quản Lý Workflow
Cho team và project nhỏ, GitHub Projects tiện quản lý editorial content trực tiếp GitHub. Chúng giống project management boards như Trello, nhưng columns link trực tiếp issues và pull requests.
Ví dụ, dùng template "Automated kanban with reviews" để new issues và pull requests tự thêm vào board. Khi reviewer bắt đầu review hoặc approve pull request, issue card chuyển cột tiếp. Theo dõi active issues và stage trong editorial process.
Cho project lớn hơn bao gồm hơn docs, dùng project-bot GitHub App setup automation rules. Ví dụ, thêm specific label hoặc assign specific reviewer trigger automatic card movement. Hoặc tích hợp documentation management vào project management workflow lớn dùng Jira.
Xem sample app demo
project-botapp trong GitHub Project.
Tạo Documentation
Section này outline tạo documentation chi tiết, từ drafting đến publication.
Viết Và Sửa Docs
Bước đầu editorial workflow: viết docs. Xem tips viết documentation tại A Beginner's Guide to Writing Documentation từ Write the Docs.
Ví dụ, tạo article về Rails blog app, tạo file Markdown blog-posts.md trong Jekyll docs directory:
---
layout: default
title: Blog Posts
nav_order: 1
---
## Creating a Blog Post
...
Khi viết code, bạn check syntax khi viết dùng syntax highlighters và code linters. Nếu viết docs trong code editor, dùng linters tương tự check spelling và grammar khi viết. Cũng có linters check Markdown formatting.
Ví dụ, VSCode cho preview Markdown files trực tiếp trong editor, có extension Markdownlint linter check lỗi Markdown syntax.
Cũng có prose linter phổ biến Vale, có extensions VSCode và editors khác.
Lợi ích khác viết Markdown trong code editor: không cần switch editors viết docs và code. Với docs lưu cùng directory Rails app, dùng split layout viết documentation תוך viewing code.
Commit Changes
Đã viết document mới trong VSCode check spelling và syntax errors. Bước tiếp: tạo branch mới commit change lên 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 lên branch docs/blog-post remote GitHub repository.
Cuối cùng, trên GitHub, tạo pull request giữa branch mới và master (hoặc main). Pull request cho changes reviewed và approved như code khác trong project.
Review Và Approve Docs
Merge documentation changes vào repository nguy hiểm như software development. Bạn deploy changes documentation mà customer và user rely on, nên muốn review process rigorous. Tốt nếu có several reviewers: developer, product manager, technical writer, editor.
Track changes mọi người làm trên file, discuss further revisions. GitHub và tools tương tự cho view change history files, bao gồm gì changed, khi changed, ai changed.
Bạn cũng thêm GitHub Actions tự check Markdown files trước khi merge vào codebase. Với mỗi linter dùng VSCode, thêm GitHub Action tương ứng nếu có:
- Vale action
- Markdownlint action
Actions này check Markdown files spelling và syntax errors trước khi docs changes go live:
Click Details xem tại sao check không pass:
Để thêm Vale và Markdownlint vào pull request checks, copy docs.yml workflow file từ sample repository.
Cho Vale action hoạt động, có thể cần tạo file .github/styles/vocab.txt trong repository. Danh sách từ (mỗi dòng một từ) Vale sẽ ignore, như tên công ty hoặc tên thành viên team.
Nếu có GitHub Pro, Team, hoặc Enterprise account, tạo branch protection rules. Rules ngăn user merge changes trừ khi requirements met, như passing status checks hoặc approval từ ít nhất một team member.
Nhớ Netlify cũng cung cấp preview site trong list checks, reviewer check everything looks good trước merge changes và re-deploy site.
Sau khi review kỹ và merge changes documentation, Netlify re-deploy site. Truy cập live Jekyll site xem changes.
Kết Luận
Bây giờ bạn có basic documentation workflow trong GitHub cho Rails app hoặc project bất kỳ. Manage docs like code có thể đơn giản hoặc phức tạp tùy nhu cầu. Cho project nhỏ, chút automation GitHub đủ. Project lớn hơn có thể tích hợp chặt với departments/teams khác và tools khác.
Hãy xem sample GitHub repository cho Rails app và sample Jekyll site tạo trong bài. Repo bao gồm sample issues và pull request, labels. Cũng có automated GitHub Project và sample pull request template cho authors, reviewers, maintainers follow khi thêm documentation vào codebase.
Đọc thêm GitLab documentation process, có thể dùng starting point develop own. Documentation Guidelines của họ cũng có thể inspire.