Cảm ơn bạn đã đóng góp vào tài liệu của Bazel. Đây là hướng dẫn nhanh về phong cách viết tài liệu để giúp bạn bắt đầu. Nếu bạn có câu hỏi về phong cách mà hướng dẫn này chưa giải đáp, hãy làm theo Hướng dẫn về phong cách viết tài liệu cho nhà phát triển của Google.
Xác định nguyên tắc
Tài liệu về Bazel phải tuân thủ các nguyên tắc sau:
- Ngắn gọn. Sử dụng ít từ nhất có thể.
- Rõ ràng. Sử dụng ngôn ngữ đơn giản. Viết không dùng thuật ngữ chuyên môn để người đọc ở trình độ lớp 5 có thể hiểu được.
- Nhất quán. Sử dụng cùng một từ hoặc cụm từ cho các khái niệm lặp lại trong suốt tài liệu.
- Chính xác. Viết theo cách sao cho nội dung luôn chính xác càng lâu càng tốt bằng cách tránh thông tin dựa trên thời gian và lời hứa cho tương lai.
Viết
Phần này chứa các mẹo viết cơ bản.
Tiêu đề
- Tiêu đề cấp trang bắt đầu từ H2. (Tiêu đề H1 được dùng làm tiêu đề trang.)
Hãy tạo tiêu đề ngắn gọn nhất có thể. Bằng cách này, tiêu đề sẽ vừa với mục lục mà không bị xuống dòng.
- Có: Quyền
- Không: Ghi chú ngắn gọn về quyền
Sử dụng cách viết hoa đầu câu cho tiêu đề
- Có: Thiết lập không gian làm việc
- Không: Thiết lập không gian làm việc
Cố gắng tạo tiêu đề dựa trên nhiệm vụ hoặc có thể thực hiện. Nếu tiêu đề mang tính khái niệm, thì tiêu đề đó có thể dựa trên sự hiểu biết, nhưng hãy viết theo những gì người dùng làm.
- Có: Duy trì thứ tự biểu đồ
- Không: Về việc duy trì thứ tự biểu đồ
Tên
Viết hoa danh từ riêng, chẳng hạn như Bazel và Starlark.
- Có: Ở cuối bản dựng, Bazel in các mục tiêu được yêu cầu.
- Không: Ở cuối bản dựng, bazel in các mục tiêu được yêu cầu.
Hãy nhất quán. Không giới thiệu tên mới cho các khái niệm hiện có. Nếu có, hãy sử dụng thuật ngữ được xác định trong Bảng chú giải.
- Ví dụ: nếu bạn đang viết về việc đưa ra lệnh trên một thiết bị đầu cuối, thì đừng sử dụng cả thiết bị đầu cuối và dòng lệnh trên trang.
Phạm vi trang
Mỗi trang phải có một mục đích và mục đích đó phải được xác định ngay từ đầu. Điều này giúp người đọc tìm thấy những gì họ cần nhanh hơn.
- Có: Trang này trình bày cách cài đặt Bazel trên Windows.
- Không: (Không có câu giới thiệu.)
Ở cuối trang, hãy cho người đọc biết việc cần làm tiếp theo. Đối với những trang nơi không có hành động rõ ràng, bạn có thể đưa vào các đường liên kết đến các khái niệm, ví dụ tương tự hoặc các cách khác để khám phá.
Tiêu đề
Trong tài liệu về Bazel, đối tượng chủ yếu phải là người dùng – những người sử dụng Bazel để xây dựng phần mềm của họ.
Gọi người đọc là "bạn". (Nếu vì lý do nào đó mà bạn không thể sử dụng "bạn", hãy sử dụng ngôn ngữ trung tính về giới tính, chẳng hạn như "họ".)
- Có: Để tạo mã Java bằng Bazel, bạn phải cài đặt JDK.
- CÓ THỂ: Để tạo mã Java bằng Bazel, người dùng phải cài đặt JDK.
- Không: Để tạo mã Java bằng Bazel, người dùng phải cài đặt JDK.
Nếu đối tượng của bạn KHÔNG phải là người dùng Bazel nói chung, hãy xác định đối tượng ở đầu trang hoặc trong phần. Các đối tượng khác có thể bao gồm người duy trì, người đóng góp, người di chuyển hoặc các vai trò khác.
Tránh sử dụng "chúng tôi". Trong tài liệu dành cho người dùng, không có tác giả; chỉ cần cho mọi người biết những gì có thể.
- Có: Khi Bazel phát triển, bạn nên cập nhật cơ sở mã để duy trì khả năng tương thích.
- Không: Bazel đang phát triển và chúng tôi sẽ thực hiện các thay đổi đối với Bazel. Đôi khi, những thay đổi này sẽ không tương thích và yêu cầu người dùng Bazel thực hiện một số thay đổi.
Temporal
Nếu có thể, hãy tránh các thuật ngữ định hướng mọi thứ theo thời gian, chẳng hạn như tham chiếu đến các ngày cụ thể (Quý 2 năm 2022) hoặc nói "hiện tại", "hiện tại" hoặc "sắp tới". Những thuật ngữ này nhanh chóng trở nên lỗi thời và có thể không chính xác nếu đó là dự đoán trong tương lai. Thay vào đó, hãy chỉ định cấp phiên bản, chẳng hạn như "Bazel X.x trở lên hỗ trợ <feature> hoặc đường liên kết đến vấn đề trên GitHub.
- Có: Bazel 0.10.0 trở lên hỗ trợ tính năng lưu vào bộ nhớ đệm từ xa.
- Không: Bazel sẽ sớm hỗ trợ tính năng lưu vào bộ nhớ đệm từ xa, có thể là vào tháng 10 năm 2017.
Tense
Sử dụng thì hiện tại. Tránh sử dụng thì quá khứ hoặc thì tương lai, trừ phi thực sự cần thiết để làm rõ.
- Có: Bazel đưa ra lỗi khi nó tìm thấy các phần phụ thuộc không tuân thủ quy tắc này.
- Không: Nếu Bazel tìm thấy một phần phụ thuộc không tuân thủ quy tắc này, Bazel sẽ đưa ra lỗi.
Nếu có thể, hãy sử dụng câu chủ động (trong đó chủ ngữ tác động lên một đối tượng) thay vì câu bị động (trong đó một đối tượng bị chủ ngữ tác động). Nói chung, câu chủ động giúp câu rõ ràng hơn vì cho biết ai chịu trách nhiệm. Nếu việc sử dụng câu chủ động làm giảm độ rõ ràng, hãy sử dụng câu bị động.
- Có: Bazel khởi tạo X và sử dụng kết quả đầu ra để tạo Y.
- Không: X được Bazel khởi tạo, sau đó Y sẽ được tạo bằng kết quả đầu ra.
Giọng điệu
Viết với giọng điệu thân thiện với doanh nghiệp.
Tránh sử dụng ngôn ngữ thông tục. Khó dịch hơn các cụm từ dành riêng cho tiếng Anh.
- Có: Bộ quy tắc tốt
- Không: Vậy bộ quy tắc tốt là gì?
Tránh sử dụng ngôn ngữ quá trang trọng. Hãy viết như thể bạn đang giải thích khái niệm cho một người tò mò về công nghệ nhưng không biết chi tiết.
Định dạng
Loại tệp
Để dễ đọc, hãy xuống dòng ở 80 ký tự. Các đường liên kết hoặc đoạn mã dài có thể dài hơn, nhưng phải bắt đầu trên một dòng mới. Ví dụ:
Liên kết
Sử dụng văn bản liên kết mang tính mô tả thay vì "tại đây" hoặc "bên dưới". Cách này giúp bạn dễ dàng quét tài liệu và phù hợp hơn với trình đọc màn hình.
- Có: Để biết thêm chi tiết, hãy xem bài viết [Cài đặt Bazel].
- Không: Để biết thêm chi tiết, hãy xem bài viết [tại đây].
Kết thúc câu bằng đường liên kết, nếu có thể.
- Có: Để biết thêm chi tiết, hãy xem [đường liên kết].
- Không: Xem [đường liên kết] để biết thêm thông tin.
Danh sách
- Sử dụng danh sách có thứ tự để mô tả cách hoàn thành một nhiệm vụ theo các bước
- Sử dụng danh sách không có thứ tự để liệt kê những việc không dựa trên nhiệm vụ. (Vẫn phải có một thứ tự nào đó, chẳng hạn như theo bảng chữ cái, mức độ quan trọng, v.v.)
- Viết theo cấu trúc song song. Ví dụ:
- Tạo tất cả các mục trong danh sách thành câu.
- Bắt đầu bằng các động từ có cùng thì.
- Sử dụng danh sách có thứ tự nếu có các bước cần làm theo.
Phần giữ chỗ
Sử dụng dấu ngoặc nhọn để biểu thị một biến mà người dùng nên thay đổi. Trong Markdown, hãy thoát dấu ngoặc nhọn bằng dấu gạch chéo ngược:
\<example\>.- Có:
bazel help <command>: In trợ giúp và các lựa chọn cho<command> - Không: bazel help command: In trợ giúp và các lựa chọn cho "command"
- Có:
Đặc biệt đối với các mẫu mã phức tạp, hãy sử dụng phần giữ chỗ có ý nghĩa trong ngữ cảnh.
Mục lục
Sử dụng mục lục được tạo tự động do trang web hỗ trợ. Không thêm mục lục thủ công.
Mã
Mẫu mã là trợ thủ đắc lực của nhà phát triển. Có lẽ bạn đã biết cách viết những mẫu mã này rồi, nhưng sau đây là một vài mẹo.
Nếu đang tham chiếu đến một đoạn mã nhỏ, bạn có thể nhúng đoạn mã đó vào một câu. Nếu bạn muốn người đọc sử dụng mã, chẳng hạn như sao chép một lệnh, hãy sử dụng khối mã.
Khối mã
- Tạo nội dung ngắn gọn. Loại bỏ tất cả văn bản dư thừa hoặc không cần thiết khỏi mẫu mã.
- Trong Markdown, hãy chỉ định loại khối mã bằng cách thêm ngôn ngữ của mẫu.
```shell
...
- Phân tách lệnh và kết quả đầu ra thành các khối mã khác nhau.
Định dạng mã trong dòng
- Sử dụng kiểu mã cho tên tệp, thư mục, đường dẫn và các đoạn mã nhỏ.
- Sử dụng kiểu mã trong dòng thay vì chữ nghiêng, "dấu ngoặc kép" hoặc chữ in đậm.
- Có:
bazel help <command>: In trợ giúp và các lựa chọn cho<command> - Không: bazel help command: In trợ giúp và các lựa chọn cho "command"
- Có: