Quy trình công việc tài liệu hiện đại ngày càng trở nên đan xen với quy trình phát triển phần mềm. Bạn có thể theo dõi các vấn đề về tài liệu trong GitHub hoặc Jira hoặc bạn có thể viết tài liệu trong các nhận xét mã hoặc tệp Markdown. Các nhà phát triển trong nhóm của bạn có thể làm việc trực tiếp với người viết kỹ thuật hoặc họ có thể viết tài liệu một cách độc lập. Tài liệu thường được lưu trữ trong kho mã, được kiểm tra chất lượng bằng linters và được xuất bản liên tục trên các trang tĩnh. Các tác giả kỹ thuật gần đây đã đặt ra thuật ngữ docs-like-code hoặc docs-as-code để mô tả loại quy trình làm việc này.
Docs-as-code được xác định bằng cách tự động hóa. Nó bao gồm việc tạo, cập nhật, xem xét và phê duyệt tài liệu bằng cách sử dụng các công cụ phát triển quen thuộc:
- Trình theo dõi vấn đề
- Công cụ kiểm soát phiên bản
- Tệp văn bản thuần túy
- Trình chỉnh sửa văn bản và mã
- Trình tạo trang web tĩnh
- Xuất bản liên tục
Tài liệu có thể được lưu trữ trong cùng một kho lưu trữ với mã liên quan, giúp dễ dàng đảm bảo tài liệu được cập nhật cùng với mã.
Quy trình làm việc này linh hoạt và thích ứng với nhiều sự kết hợp của các công cụ và phương pháp luận. Với mục đích minh họa, hướng dẫn này phát triển quy trình làm việc docs-as-code cho ứng dụng Rails bằng cách sử dụng các công cụ dựa trên Ruby, chẳng hạn như Jekyll. Các tài liệu được lưu trữ cùng với ứng dụng trong GitHub và được quản lý bằng cách sử dụng các vấn đề GitHub, nhãn, dự án và đánh giá yêu cầu kéo. Ví dụ này minh họa các nguyên tắc docs-as-code có thể được điều chỉnh cho phù hợp với các công cụ khác và được tích hợp vào các quy trình công việc khác.
Điều kiện tiên quyết
Hướng dẫn này dành cho các nhà phát triển. Bạn nên làm quen với các công cụ sau:Git, trình chỉnh sửa mã và Markdown. Bài viết này mô tả cách sử dụng các công cụ này để tạo dòng công việc tài liệu.
Đi kèm với bài viết này là một trang web mẫu trực tiếp, được lưu trữ bởi Netlify và một kho lưu trữ GitHub mẫu.
Để làm theo bài viết này, hãy tạo một ứng dụng blog đơn giản trong Rails bằng một 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 một trang chỉ mục:
Rails.application.routes.draw do
resources :posts
root 'posts#index'
end
Cuối cùng, chạy di chuyển cơ sở dữ liệu và khởi động máy chủ Rails để kiểm tra xem mọi thứ có hoạt động không:
rails db:migrate
rails s
Điều hướng đến localhost:3000 . Bạn sẽ thấy một danh sách trống các bài đăng và một liên kết để tạo một bài mới.
Tạo Chiến lược Nội dung
Lập kế hoạch là bước đầu tiên trong việc phát triển quy trình làm việc tài liệu, giống như với phần mềm. Kế hoạch cho tài liệu của bạn nên bao gồm chiến lược nội dung, chiến lược này xác định chủ đề nào cần được lập thành tài liệu và cách thức.
Để bắt đầu phát triển chiến lược nội dung, hãy trả lời các câu hỏi sau:
- Đối tượng dự định của bạn là ai?
- Họ là nhà phát triển, ít người dùng kỹ thuật hơn hay cả hai?
- Họ có được phép đóng góp vào mã hoặc tài liệu của bạn không?
- Họ là nội bộ hay bên ngoài công ty của bạn hay cả hai?
- Người dùng đang cố gắng hoàn thành điều gì?
- Người dùng đang cố gắng giải quyết vấn đề gì bằng cách tham khảo tài liệu của bạn?
- Người dùng sẽ tham khảo tài liệu của bạn như thế nào?
- Một chỉ số đọc đơn giản có đủ không?
- Người dùng có cần quyền đặc biệt để truy cập tài liệu không?
Ví dụ:hãy tưởng tượng bạn có một ứng dụng Rails với một API đi kèm. Đối với khách hàng, bạn có thể muốn phát triển một hướng dẫn sử dụng công khai cho tất cả các tính năng giao diện người dùng của mình. Câu chuyện của người dùng có thể là "Với tư cách là người dùng, tôi muốn tạo một bài đăng trên blog."
Bạn cũng có thể tạo tài liệu tham khảo cho các nhà phát triển. Câu chuyện của nhà phát triển có thể là, "Là một nhà phát triển, tôi muốn truy xuất tất cả các bài đăng trên blog của một người dùng cụ thể."
Bạn có thể sử dụng trình tạo trang web tĩnh, chẳng hạn như Jekyll hoặc WordPress, để hiển thị tài liệu người dùng trong môi trường thân thiện với người dùng, có thương hiệu. Đối với các nhà phát triển nội bộ của bạn, một trang web do YARD tạo đơn giản có thể là đủ. Hướng dẫn này sẽ cho bạn thấy các ví dụ về cả hai.
Tài liệu cũng có thể được tích hợp vào quy trình làm việc hiện tại của bạn. Ví dụ:nếu nhóm của bạn viết mã trong 2 tuần chạy nước rút, hãy cân nhắc quản lý tài liệu của bạn theo cùng một lịch trình.
Bạn cũng có thể theo dõi các vấn đề về tài liệu cùng với các vấn đề về mã. Tạo sự cố cho mọi tính năng hoặc lỗi của tài liệu. Một tính năng sẽ là một bài viết hoặc một phần nội dung mới và lỗi sẽ là bất kỳ lỗi nào, thiếu sót, đánh máy hoặc vấn đề khác cần được sửa chữa.
Thu thập phản hồi là một phần quan trọng của chiến lược nội dung. Cân nhắc thêm một cách để người dùng liên hệ với bạn bằng phản hồi trên mọi trang tài liệu hoặc đóng góp cho tài liệu thông qua GitHub. A Phản hồi nút thường chỉ là một biểu mẫu chuyển đến địa chỉ email của công ty; (những) người được giao cho nhiệm vụ này sau đó có thể nhận từng mục phản hồi và biến nó thành vấn đề Jira hoặc GitHub để xem xét và thực hiện.
Để đảm bảo một phong cách nhất quán và sử dụng thuật ngữ chính xác, hãy tạo một hướng dẫn về phong cách công ty hoặc làm theo một hướng dẫn hiện có. Dưới đây là một số ví dụ về hướng dẫn kiểu tài liệu sẽ hoạt động cho hầu hết các dự án phần mềm:
- Hướng dẫn kiểu tài liệu dành cho nhà phát triển của Google
- Hướng dẫn Kiểu Tài liệu GitLab
- Hướng dẫn Kiểu Viết của Microsoft
Dưới đây là một số bài đọc thêm về chiến lược nội dung để giúp bạn bắt đầu:
- Chiến lược nội dung DX với Cổng thông tin dành cho nhà phát triển
- Sơ lược về Chiến lược Nội dung Tài liệu
Xây dựng Trang web Tài liệu
Từ chiến lược nội dung của mình, bạn có thể xác định cách tài liệu của mình sẽ được hiển thị cho khán giả dự định. Xác định ai sẽ viết tài liệu của bạn cũng sẽ giúp thông báo quyết định này. Ví dụ:nếu các nhà phát triển và cộng tác viên sẽ viết tài liệu trong các bình luận mã, thì RDoc hoặc YARD có thể được sử dụng để tạo một trang tài liệu tĩnh đơn giản từ các bình luận này. Nếu tài liệu người dùng sẽ được viết trong các tệp Markdown, thì một trình tạo trang web tĩnh, chẳng hạn như Jekyll, sẽ là lựa chọn tốt hơn để xuất bản tài liệu của bạn. Tất nhiên, bạn cũng có thể tạo một trang web từ đầu phù hợp với nhóm và dự án của bạn.
Bài viết này sử dụng Jekyll và YARD để minh họa cả hai loại trang web tài liệu cho ứng dụng Rails. Lưu ý rằng Jekyll dựa trên Ruby và tích hợp tốt vào ứng dụng Rails.
Jekyll
Mục đích của Jekyll là chuyển đổi văn bản thuần túy thành một trang web tĩnh. Jekyll tạo một _site thư mục chứa các tệp trang web tĩnh có thể được xuất bản bởi bất kỳ dịch vụ lưu trữ nào. Đẩy các tệp này lên GitHub có nghĩa là bạn có thể sử dụng các công cụ xuất bản liên tục, chẳng hạn như Netlify, để xuất bản tài liệu của mình.
Quy trình làm việc đơn giản nhất với Jekyll liên quan đến việc viết tài liệu trong các tệp Markdown và đẩy chúng lên GitHub. Nếu bạn sử dụng Netlify, nó sẽ tự động triển khai trang web khi bạn hợp nhất những thay đổi này vào kho lưu trữ. Quá trình này được mô tả chi tiết hơn trong phần tiếp theo.
Để tạo trang web Jekyll, hãy cài đặt Jekyll và Bundler từ thư mục gốc của ứng dụng Rails của bạn (ví dụ:/blog ):
gem install jekyll bundler
Tạo một trang web Jekyll và chạy nó từ một máy chủ phát triển cục bộ chỉ yêu cầu ba lệnh:
jekyll new docs
cd docs
bundle exec jekyll serve
Điều này tạo ra một /docs thư mục chứa một trang Jekyll tối thiểu (mặc định là một chủ đề blog được gọi là Minima). Bạn có thể sử dụng điều này làm cơ sở cho trang web tài liệu Jekyll tùy chỉnh của mình. Ngoài ra, bạn có thể cài đặt chủ đề tài liệu, chẳng hạn như just-the-docs , đi kèm với điều hướng thanh bên và chức năng tìm kiếm trang web.
Hướng dẫn này sẽ sử dụng just-the-docs chủ đề. Để cài đặt nó, hãy chạy phần sau từ /docs thư mục:
bundle add just-the-docs
Xóa minima chủ đề từ Gemfile vì nó là chủ đề mặc định mà bạn sẽ không sử dụng nữa. Bạn cũng có thể xóa posts thư mục.
Tiếp theo, thêm chủ đề này vào _config.yml của Jekyll tập tin. Bạn cũng có thể tùy chỉnh tiêu đề và mô tả trang web của mình khi bạn ở đây:
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 lại máy chủ và bạn sẽ thấy một trang web tài liệu gần như trống rỗng:
Kiểm tra tài liệu về chủ đề Jekyll của bạn để xem thư mục nào sẽ chứa các tệp Markdown của bạn. Đối với just-the-docs Các tệp Markdown có thể nằm trong thư mục gốc, tương ứng với đường dẫn cơ sở của trang web của bạn. Tạo tệp Markdown mới trong thư mục gốc để xem nó hoạt động như thế nào:
---
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 lại máy chủ để xem tài liệu mẫu mới của bạn:
Bây giờ bạn có một trang web Jekyll cơ bản trong /docs thư mục trong thư mục ứng dụng Rails của bạn! Xem tài liệu về Jekyll để được trợ giúp tùy chỉnh chủ đề Jekyll hoặc viết chủ đề của riêng bạn.
YARD
Trình tạo tài liệu, chẳng hạn như Rdoc và YARD, tạo tài liệu dành cho nhà phát triển từ các nhận xét mã. Bạn có thể tạo một trang tài liệu độc lập bằng YARD, trang này chấp nhận Rdoc và các cú pháp khác. Trong ví dụ này, chúng tôi sẽ thêm tài liệu YARD vào trang Jekyll hiện có của chúng tôi. Jekyll có thể xuất bản các tệp tĩnh do YARD tạo ra theo đường dẫn như /dev . Bạn cũng có thể tự sử dụng YARD để tạo trang web tài liệu của mình.
Khi Rails tạo một ứng dụng, nó cũng tạo ra một số nhận xét mã 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 cách YARD sử dụng những nhận xét này để tạo trang tài liệu, hãy chạy yard doc hoặc yardoc lệnh từ thư mục gốc của ứng dụng Rails của bạn:
yardoc --output-dir docs/dev app/**/*.rb
Nếu
yardoclệnh không hoạt động, hãy cài đặt đá quý YARD vớibundle install yard.
YARD sẽ đặt các tệp đầu ra của nó trong output-dir , được đặt thành thư mục Jekyll /docs/dev trong lệnh trên. Jekyll hiện có thể xuất bản các tệp trang web của YARD với đường dẫn cơ sở là /dev .
Tài liệu phức tạp hơn có thể được tạo bằng cách sử dụng RDoc hoặc cú pháp khác (xem tài liệu YARD), nhưng chúng tôi sẽ sử dụng tài liệu hiện có ở đây.
Khởi động máy chủ Jekyll và điều hướng đến localhost:4000/dev để xem tài liệu do YARD tạo của bạn:
Tại thời điểm này, không có cách nào để điều hướng đến các tài liệu dành cho nhà phát triển này từ trang web chính của Jekyll. Để thêm liên kết từ trang Jekyll vào tài liệu dành cho nhà phát triển, hãy thêm phần sau vào docs/_config.yml :
# Aux links for the upper right navigation
aux_links:
"Developer Documentation":
- "/dev"
Điều này kết thúc cuộc thảo luận của Jekyll và YARD. Giờ đây, trang web tài liệu của bạn đã được thiết lập, các nhà phát triển và người viết có thể chỉ cần viết nội dung trong tệp Markdown (hoặc nhận xét mã) và đẩy chúng lên GitHub. Phần tiếp theo giải thích cách triển khai các tài liệu này với việc xuất bản liên tục.
Xuất bản và triển khai liên tục với Netlify
Việc xuất bản liên tục rất thuận tiện cho các trang tài liệu vì trang trực tiếp có thể được cập nhật tự động khi các thay đổi đối với tài liệu được chấp thuận và hợp nhất vào kho lưu trữ. Hướng dẫn này sử dụng Netlify cho mục đích này, nhưng có sẵn các công cụ khác, chẳng hạn như GitHub Pages, GitLab Pages và Firebase.
Trang web chúng tôi đang xây dựng cho đến nay được lưu trữ bởi Netlify:Trang web Tài liệu.
Để thiết lập Netlify cho trang tài liệu của bạn, hãy bắt đầu bằng cách đăng ký tài khoản Netlify và kết nối tài khoản đó với kho lưu trữ GitHub chứa ứng dụng Rails của bạn.
Sử dụng các cài đặt 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ố cài đặt không khả dụng khi tạo trang Netlify, hãy nhấp vào Triển khai cho bây giờ. Sau đó, bạn có thể hủy và quay lại Cài đặt triển khai . Đặt thư mục cơ sở thành
docsđể đảm bảo rằng Netlify triển khai trang web tài liệu Jekyll của bạn thay vì ứng dụng Rails của bạn.
Khi Netlify hoàn tất việc triển khai trang web Jekyll của bạn, hãy điều hướng đến trang web đang hoạt động để đảm bảo rằng mọi thứ đều ổn.
Một lợi ích của việc sử dụng Netlify là nó cung cấp liên kết xem trước trực tiếp trực tiếp từ mỗi yêu cầu kéo:
Sau đó, bạn có thể kiểm tra xem các thay đổi của mình có được xuất bản chính xác hay không trước khi hợp nhất yêu cầu kéo và kích hoạt triển khai lại trang web của bạn. Phần tiếp theo trình bày chi tiết hơn về quy trình làm việc này.
Thiết lập Quy trình biên tập trong GitHub
Với chiến lược viết tài liệu và trang web để xuất bản tài liệu đó, bạn có thể bắt đầu viết tài liệu và tích hợp chúng vào quy trình làm việc phần mềm của mình.
Quy trình biên tập điển hình bao gồm việc soạn thảo một tài liệu, xem xét tài liệu và sau đó xuất bản nó. Các nhà văn nên thực hiện đánh giá tác phẩm của họ, nhưng các biên tập viên, người quản lý và các bên liên quan thường là một phần của quá trình đánh giá cuối cùng. Bởi vì điều này tương tự với quy trình phát triển phần mềm, bạn có thể sử dụng các công cụ phát triển phần mềm để làm cho quy trình hiệu quả hơn.
Dưới đây là quy trình biên tập mẫu cho một nhóm sử dụng GitHub:
- [Writer] Tạo hoặc cập nhật tệp theo yêu cầu hoặc lỗi của tính năng tài liệu (như đã nêu trong vấn đề GitHub).
- [Writer] Đẩy thay đổi sang một nhánh GitHub.
- [Writer] Mở một yêu cầu kéo.
- [Người đánh giá] Xem lại các thay đổi.
- [Người đánh giá / Người bảo trì] Hợp nhất các thay đổi vào hệ thống lưu trữ, điều này sẽ kích hoạt một bản dựng mới của trang tài liệu.
GitHub tự động quản lý lịch sử thay đổi nội dung của bạn, lịch sử này cũng là chìa khóa trong quy trình làm việc do tài liệu dưới dạng mã. Bạn có thể xem những gì đã được thay đổi, ai đã thay đổi, khi nào nó được thay đổi, cũng như lý do hoặc cách nó được thay đổi (nếu được đề cập trong các nhận xét, thảo luận hoặc một vấn đề liên quan). Thông tin này được lưu trữ ở một nơi để tất cả các thành viên trong nhóm của bạn có thể xem bất kỳ lúc nào.
Vấn đề và Nhãn
Bạn có thể sử dụng các mẫu vấn đề tương tự cho tài liệu mới mà bạn sẽ sử dụng cho mã. Điều này cho phép các thành viên cộng đồng yêu cầu tài liệu có thể bị thiếu hoặc thông báo lỗi cho nhóm. Người quản lý cũng có thể sử dụng các vấn đề để chỉ định các nhà phát triển hoặc người viết cho các nhiệm vụ tài liệu.
Để phân biệt vấn đề tài liệu với vấn đề mã, bạn có thể sử dụng nhãn. Thêm documentation nhãn để cho biết rằng nó liên quan đến tài liệu. Bạn cũng có thể tạo nhãn cho các vấn đề tài liệu cụ thể, chẳng hạn như docs::feature hoặc docs::fix .
Bạn có thể thêm hướng dẫn vào các mẫu vấn đề của mình liên quan đến tiêu đề vấn đề hoặc các nhãn thích hợp, giống như cách bạn làm đối với các vấn đề liên quan đến mã.
Các nhãn quy trình làm việc, chẳng hạn như docs::in progress và docs::in review , cũng hữu ích. Chúng phản ánh những gì hiện đang được nghiên cứu.
Khi xác định quy trình tài liệu của bạn, hãy nhớ chỉ định ai chịu trách nhiệm thay đổi các nhãn này và khi nào. Ví dụ:người viết bản nháp sẽ thay đổi nhãn thành docs::in progress khi họ bắt đầu viết bản nháp. Khi người đánh giá nhận được bản nháp, người đánh giá nên thay đổi nhãn vấn đề thành docs::in review .
Quản lý quy trình làm việc
Đối với các nhóm và dự án nhỏ, sử dụng Dự án GitHub là một cách thuận tiện để quản lý nội dung biên tập của bạn trực tiếp từ GitHub. Chúng tương tự như các ban quản lý dự án, chẳng hạn như trong Trello, nhưng các cột có thể được liên kết trực tiếp với các vấn đề và các yêu cầu kéo.
Ví dụ:sử dụng mẫu "Kanban tự động có đánh giá" để các vấn đề mới và yêu cầu kéo được tự động thêm vào bảng. Khi người đánh giá bắt đầu xem xét hoặc phê duyệt yêu cầu kéo, thẻ vấn đề sẽ chuyển sang cột tiếp theo. Điều này cho phép bạn theo dõi các vấn đề đang hoạt động và chúng đang ở đâu trong quá trình biên tập.
Đối với các dự án lớn hơn không chỉ bao gồm tài liệu, hãy sử dụng project-bot Ứng dụng GitHub để thiết lập các quy tắc tự động hóa. Ví dụ:thêm một nhãn cụ thể hoặc chỉ định một người đánh giá cụ thể sẽ kích hoạt chuyển động thẻ tự động. Ngoài ra, bạn có thể tích hợp quản lý tài liệu vào quy trình quản lý dự án lớn hơn của mình bằng cách sử dụng một công cụ như Jira.
Xem ứng dụng mẫu để biết phần trình diễn của
project-botứng dụng trong Dự án GitHub.
Tạo tài liệu
Phần này trình bày chi tiết hơn về việc tạo tài liệu, từ khi soạn thảo đến xuất bản.
Viết và Chỉnh sửa Tài liệu
Bước đầu tiên trong quy trình biên tập của bạn là viết một số tài liệu. Để biết các mẹo về cách viết tài liệu, hãy xem Hướng dẫn Viết Tài liệu cho Người mới bắt đầu từ Viết Tài liệu.
Ví dụ:để tạo một bài viết về ứng dụng blog Rails của bạn, hãy tạo một tệp Markdown mới có tên là blog-posts.md trong tài liệu Jekyll docs của bạn thư mục:
---
layout: default
title: Blog Posts
nav_order: 1
---
## Creating a Blog Post
...
Khi bạn đang viết mã, có thể bạn đang kiểm tra cú pháp khi viết bằng cách sử dụng bút đánh dấu cú pháp và gạch lót mã. Nếu bạn viết tài liệu của mình trong một trình soạn thảo mã, bạn có thể sử dụng các linters tương tự để kiểm tra lỗi chính tả và các vấn đề ngữ pháp khi bạn viết. Ngoài ra còn có các linters kiểm tra định dạng Markdown của bạn.
Ví dụ:VSCode cho phép bạn xem trước các tệp Markdown trực tiếp trong trình chỉnh sửa và nó có một phần mở rộng cho trình liên kết Markdownlint, kiểm tra lỗi trong cú pháp Markdown của bạn.
Ngoài ra còn có một phần mềm văn xuôi phổ biến được gọi là Vale, có phần mở rộng trong VSCode và các trình soạn thảo khác.
Một phần thưởng khác khi viết Markdown trong trình soạn thảo mã của bạn là bạn không cần phải chuyển đổi giữa các trình chỉnh sửa để viết tài liệu và mã cho dự án của mình. Với các tài liệu của bạn được lưu trữ trong cùng một thư mục với ứng dụng Rails, bạn có thể sử dụng bố cục phân tách để viết tài liệu trong khi xem mã.
Cam kết thay đổi
Bạn đã viết một tài liệu mới trong VSCode và kiểm tra nó để tìm lỗi chính tả và lỗi cú pháp. Bước tiếp theo là tạo một nhánh mới và cam kết thay đổi đối với 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
Đẩy cam kết này vào docs/blog-post nhánh trong kho lưu trữ GitHub từ xa.
Cuối cùng, trên GitHub, hãy tạo một yêu cầu kéo giữa nhánh mới của bạn và nhánh chính (hoặc chính). Yêu cầu kéo này cho phép các thay đổi của bạn được xem xét và phê duyệt giống như bất kỳ mã nào khác trong dự án.
Xem xét và Phê duyệt Tài liệu
Việc hợp nhất các thay đổi tài liệu vào một kho lưu trữ có thể nguy hiểm như trong quá trình phát triển phần mềm. Bạn đang triển khai các thay đổi đối với tài liệu mà khách hàng và người dùng của bạn dựa vào, vì vậy, bạn sẽ muốn đảm bảo quy trình xem xét nghiêm ngặt. Bạn nên có một số người đánh giá tham gia, bao gồm nhà phát triển, người quản lý sản phẩm, người viết kỹ thuật và người biên tập.
Theo dõi những thay đổi mà mọi người thực hiện đối với tệp và thảo luận về bất kỳ bản sửa đổi nào cần thiết. GitHub và các công cụ tương tự cho phép bạn xem lịch sử thay đổi của các tệp của mình, bao gồm những gì đã được thay đổi, thời điểm thực hiện thay đổi và ai đã thực hiện.
Bạn cũng có thể thêm GitHub Actions để tự động kiểm tra các tệp Markdown của mình trước khi ai đó hợp nhất chúng vào cơ sở mã. Đối với mỗi linter mà bạn sử dụng trong VSCode, hãy thêm Hành động GitHub tương ứng nếu nó tồn tại:
- Hành động khác nhau
- Markdownlint action
Những hành động này sẽ kiểm tra các tệp Markdown của bạn để tìm các lỗi chính tả và lỗi cú pháp khác nhau trước khi các thay đổi đối với tài liệu của bạn có hiệu lực:
Nhấp vào Chi tiết để xem tại sao séc không vượt qua:
Để thêm Vale và Markdownlint vào kiểm tra yêu cầu kéo của bạn, hãy sao chép tệp dòng công việc docs.yml từ kho lưu trữ mẫu.
Để hành động Vale hoạt động, bạn có thể cần tạo .github/styles/vocab.txt tệp trong kho lưu trữ của bạn. Đây là danh sách các từ (một từ trên mỗi dòng) sẽ bị Vale bỏ qua, chẳng hạn như tên công ty của bạn hoặc tên của những người trong nhóm của bạn.
Nếu bạn có tài khoản GitHub Pro, Team hoặc Enterprise, bạn có thể tạo các quy tắc bảo vệ chi nhánh. Các quy tắc này ngăn người dùng hợp nhất các thay đổi trừ khi đáp ứng các yêu cầu nhất định, chẳng hạn như vượt qua kiểm tra trạng thái hoặc nhận được sự chấp thuận của ít nhất một thành viên trong nhóm.
Hãy nhớ rằng Netlify cũng cung cấp bản xem trước trang web của bạn trong danh sách kiểm tra, vì vậy người đánh giá có thể kiểm tra xem mọi thứ có tốt không trước đó hợp nhất các thay đổi và triển khai lại trang web.
Sau khi bạn đã xem xét kỹ lưỡng và sau đó hợp nhất các thay đổi vào tài liệu của mình, Netlify sẽ triển khai lại trang web của bạn. Điều hướng đến trang web Jekyll trực tiếp của bạn để xem các thay đổi.
Kết luận
Bây giờ bạn sẽ có một quy trình làm việc tài liệu cơ bản trong GitHub cho ứng dụng Rails hoặc bất kỳ dự án nào khác. Việc quản lý các tài liệu như mã có thể đơn giản hoặc phức tạp tùy theo nhu cầu. Đối với các dự án nhỏ, một chút tự động hóa trong GitHub có thể là tất cả những gì bạn cần. Các dự án lớn hơn có thể được tích hợp chặt chẽ hơn với các phòng ban và nhóm khác và do đó, với các công cụ khác.
Hãy nhớ xem qua kho lưu trữ GitHub mẫu cho ứng dụng Rails và trang web Jekyll mẫu mà chúng tôi đã tạo trong bài viết này. Repo bao gồm các vấn đề mẫu và một yêu cầu kéo, cũng như các nhãn. Nó cũng có Dự án GitHub tự động và mẫu yêu cầu kéo mẫu để tác giả, người đánh giá và người bảo trì tuân theo khi thêm tài liệu vào cơ sở mã.
Để đọc thêm, hãy xem quy trình tài liệu của GitLab, quy trình này có thể được sử dụng làm điểm khởi đầu để phát triển tài liệu của riêng bạn. Nguyên tắc Tài liệu của họ cũng có thể cung cấp nguồn cảm hứng.