Skip to main content
Ly Hoàng
💬
0 discussions

Quy định cần nắm khi viết tài liệu Handbook

Xin chào các bạn! Vui lòng đọc kỹ file bên dưới để nắm quy định chung khi viết tài liệu, giúp cho việc trình bày tài liệu đồng bộ giữa tất cả mọi người và đạt hiệu quả cao nhất trong việc truyền đạt thông tin.

I. Phân loại tài liệu theo mục đích​

Tài liệu được phân loại theo mục đích kèm các bài viết ví dụ như sau:

Loại bàiBài ví dụ
Info
Concept/Methodology/Modeling
How-to
Process
Troubleshooting
Getting started for the first {kind of tasks} or {kind of roles}
14/90 first days of a kind of {jobs}
FAQ

II. Gợi ý sườn tài liệu mỗi bộ phận​

Topic chínhTopic con (ví dụ)
Miêu tả công việc từng vị trí trong bộ phậnVí dụ: Customer Success Engineer
Miêu tả công việc từng vai trò trong bộ phậnDevOps engineer
Product designer
14 ngày đầu tiênTất cả
DevOps engineer
Product designer
Check-list đầu công việc chính
Quy trình A
Quy trình B
FAQ

III. Cấu trúc nội dung​

Bài viết cần theo cấu trúc gồm các mục chính bên dưới.

1. Miêu tả ngắn​

Why: Một vài câu miêu tả tổng quan về nội dung và mục đích bài viết.

2. Điều kiện cần​

Liệt kê các bài viết cần đọc trước khi đọc bài viết này hoặc các điều kiện khác về kiến thức, công cụ, kinh nghiệm nếu có:

  • Bài 1
  • Bài 2
  • Bài 3

3. Nội dung chính​

Từ phần này, bạn bắt đầu nội dung chính của tài liệu.

  • Các đầu mục cần được phân chia rõ ràng theo các cấp bậc Heading để tạo mục lục và người đọc dễ theo dõi: Heading 2, Heading 3, Heading 4 ...
  • Có thể tư duy theo phương pháp 5W1H để tài liệu bao quát các nội dung quan trọng (Why, What, Who, When, Where, How).

4. Kết luận​

Ở phần này, bạn có thể nêu:

  • Kết quả kỳ vọng sau khi người đọc đọc và thực hiện theo tài liệu
  • Lưu ý, đề cập những gì tồn đọng hoặc cần xem xét thêm (nếu có)

5. Đọc thêm​

Liệt kê các bài viết liên quan nên tham khảo thêm:

  • Bài 1
  • Bài 2
  • Bài 3

 6. Tag​

Danh sách thẻ từ khóa gợi ý để tìm kiếm ra bài biết trên thanh search:

  • Từ khóa 1
  • Từ khóa 2
  • Từ khóa 3

IV. Phong cách bài viết​

1. Một số quy tắc cần nhớ​

  • Khi viết tài liệu, bạn cần đặt mình vào vị trí của người đọc. Thông thường, cách chúng ta viết tương tự như cách chúng ta nói chuyện hoặc suy nghĩ, điều này có thể dẫn đến cách diễn đạt đứt đoạn và khó theo dõi.
  • Đừng cho rằng người đọc biết tất cả những khái niệm bạn đang đề cập. Bạn cần xác định các khái niệm và thuật ngữ chính, đồng thời kèm các giải thích khi cần thiết và thêm liên kết đến tài liệu liên quan.

2. Quy định về phong cách​

2.1. Viết tắt​

Khi sử dụng từ viết tắt, hãy nhớ ghi thuật ngữ đầy đủ và để từ viết tắt trong dấu ngoặc trong lần đầu tiên. Sau đó, bạn có thể sử dụng từ viết tắt hoặc chữ cái đầu để thay thế.

2.2. Ngôn ngữ​

  • Ngôn ngữ: Tiếng Việt
  • Ngoại trừ các tài liệu thuần kỹ thuật

2.3. Heading​

  • Tiêu đề bài viết là Heading 1, từ các đầu mục trong bài sẽ là Heading 2 trở đi
  • Khuyến khích đánh số các đầu mục.
  • Định dạng đánh số đầu mục cần đồng bộ:
HeadingĐánh số
Heading 2I.
Heading 31.
Heading 41.1.
Heading 5a.
  • Không kết thúc các Heading bằng dấu : (để phù hợp khi heading hiển thị trong mục lục)

2.4. Tên riêng​

  • Viết hoa chữ cái đầu

2.5. Liệt kê​

  • Dùng bullet chấm tròn, dấu * thay vì dấu gạch ngang
  • Hyperlink vào text thay vì dán link trực tiếp vào bài viết

2.7. Hình ảnh​

  • Canh giữa bài viết, thêm caption khi cần thiết

2.8. Số​

  • Dùng dấu " , " để thể hiện đơn vị ngàn. Ví dụ: 2,000

2.9. Khoảng cách​

  • Giữa các khối (đoạn - đoạn, đoạn - hình ảnh), cần có 1 khoảng cách rộng hơn khoảng cách giữa các dòng trong 1 đoạn.