Cảm ơn bạn đã đóng góp tài liệu cho Bazel. Đây là tính năng để giúp bạn bắt đầu. Đối với mọi câu hỏi về kiểu trong hướng dẫn này, hãy làm theo Hướng dẫn quy tắc tài liệu dành cho nhà phát triển của Google.
Xác định nguyên tắc
Cá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 từ đơn giản. Viết mà không có biệt ngữ cho lớp năm cấp độ đọc.
- Nhất quán. Sử dụng các từ hoặc cụm từ giống nhau cho khái niệm lặp lại trong suốt các tài liệu.
- Chính xác. Viết theo cách mà nội dung vẫn chính xác miễn là bằng cách tránh những thông tin và lời hứa dựa trên thời gian về tương lai.
Viết
Phần này trình bày các mẹo viết cơ bản.
Tiêu đề
- Tiêu đề cấp trang bắt đầu ở H2. (Tiêu đề H1 được dùng làm tiêu đề trang.)
Tạo tiêu đề ngắn gọn ở mức hợp lý. Bằng cách này, các chỉ số này phù hợp với Quy trình kiểm tra chất lượng mà không cần gói.
- Có: Quyền
- Không: Lưu ý ngắ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
Hãy cố gắng tạo tiêu đề dựa trên nhiệm vụ hoặc khả thi. Nếu tiêu đề chỉ mang tính khái niệm, câu trả lời có thể dựa trên hiểu biết, nhưng ghi lại những gì người dùng làm.
- Có: Thứ tự bảo tồn trong biểu đồ
- Không: Về việc lưu giữ thứ tự biểu đồ
Tên
Viết hoa danh từ riêng, chẳng hạn như Bazel và Starlark.
- Có: Khi tạo xong, Bazel sẽ in các mục tiêu được yêu cầu.
- No (Không): Khi tạo xong, bazel sẽ in các mục tiêu được yêu cầu.
Đảm bảo tính nhất quán. Không sử dụng tên mới cho các khái niệm hiện có. Địa điểm áp dụng, hãy sử dụng thuật ngữ được định nghĩa trong Bảng thuật ngữ.
- Ví dụ: nếu bạn đang viết về việc tạo lệnh trên dòng lệnh, không sử dụng cả dòng lệnh và dòng lệnh trên trang.
Phạm vi trang
Mỗi trang nên có một mục đích và mục đích đó phải được xác định tại đầu tiên. Cách này giúp độc giả tìm thấy nội dung họ cần nhanh hơn.
- Có: Trang này hướng dẫn 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 các trang mà không có hành động rõ ràng, bạn có thể đưa vào đường liên kết đến các khái niệm tương tự, ví dụ hoặc những cách khác để khám phá.
Chủ đề
Trong tài liệu của Bazel, đối tượng chủ yếu phải là người dùng — những người đang 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 đó bạn không thể sử dụng "bạn", sử dụng ngôn từ trung tính, chẳng hạn như họ).
- Yes (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.
- No (Không): Đối với người dùng tạo mã Java bằng Bazel, người này 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 tại đầu trang hoặc trong phần. Các đối tượng khác có thể bao gồm người bảo trì, người đóng góp, người di trú hoặc các vai trò khác.
Tránh sử dụng từ "chúng tôi". Trong tài liệu người dùng không có tác giả; chỉ cần cho mọi người biết nhất 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 tại thời gian 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.
Thời gian
Nếu có thể, hãy tránh dùng những từ ngữ có thể giúp định hướng cho vấn đề kịp thời, chẳng hạn như tham khảo 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 bắt đầu". Những lỗi thời và có thể không chính xác nếu đó là hình chiếu 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ó: Hỗ trợ Bazel 0.10.0 trở lên lưu vào bộ nhớ đệm từ xa.
- Không: Bazel sẽ sớm hỗ trợ điều khiển từ xa lưu vào bộ nhớ đệm, có thể là vào tháng 10 năm 2017.
Tense
Sử dụng thì hiện tại. Tránh thì quá khứ hoặc thì tương lai trừ phi thực sự cần thiết để cho rõ ràng.
- Có: Bazel đưa ra lỗi khi sẽ tìm 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 theo quy tắc này, Bazel sẽ đưa ra thông báo lỗi.
Nếu có thể, hãy dùng câu chủ động (trong đó đối tượng hành động dựa trên một đối tượng) chứ không phải thể bị động (khi một đối tượng được một đối tượng thực hiện). Nhìn chung, câu chủ động sẽ giúp các câu rõ ràng hơn vì nó cho biết ai có trách nhiệm. Nếu thì hãy dùng giọng nói chủ động làm giảm âm lượng rõ ràng, còn dùng thể bị động.
- Có: Bazel khởi tạo X và sử dụng đầu ra để tạo Y.
- No (Không): X do Bazel khởi tạo, sau đó Y sẽ được tạo cùng với 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 ngôn từ thông tục. Khó dịch hơn những cụm từ dành riêng cho tiếng Anh.
- Có: Quy tắc phù hợp
- Không: Vậy bộ quy tắc hiệu quả là gì?
Tránh dùng ngôn từ trang trọng quá mức. Viết như thể bạn đang giải thích về của chúng tôi cho những 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 gói các dòng ở mức 80 ký tự. Đường liên kết dài hoặc đoạn mã có thể dài hơn, nhưng nên bắt đầu trên một dòng mới. Ví dụ:
Đường liên kết
Sử dụng văn bản liên kết mô tả thay vì "tại đây" hoặc "bên dưới". Phương pháp này giúp việc quét tài liệu dễ dàng hơn 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 phần [Cài đặt Bazel].
- Không: Để biết thêm chi tiết, hãy xem [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 [link].
- Không: Hãy xem [link] để biết thêm thông tin.
Danh sách
- Sử dụng danh sách theo thứ tự để mô tả cách hoàn thành một tác vụ theo các bước
- Sử dụng danh sách không theo thứ tự để liệt kê những nội dung không dựa trên tác vụ. (Nên vẫn được sắp xếp theo thứ tự, chẳng hạn như bảng chữ cái, tầm quan trọng, v.v.)
- Viết có cấu trúc song song. Ví dụ:
- Tạo tất cả các câu của mục trong danh sách.
- Bắt đầu với 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 thực hiện.
Phần giữ chỗ
Sử dụng dấu ngoặc góc để biểu thị một biến mà người dùng cần thay đổi. Trong Markdown, hãy thoát khỏi dấu ngoặc nhọn bằng dấu gạch chéo ngược:
\<example\>.- Có:
bazel help <command>: Ảnh in trợ giúp và tuỳ chọn cho<command> - Không: lệnh trợ giúp bazel: Trợ giúp về bản in và các tuỳ chọn cho "command"
- Có:
Đặc biệt, đối với các mã mẫu phức tạp, hãy dùng phần giữ chỗ có ý nghĩa theo ngữ cảnh.
Mục lục
Hãy sử dụng MPEG được tạo tự động mà trang web này hỗ trợ. Đừng thêm hoạch thu nhập bằng cách thủ công.
Mã
Mã mẫu là do nhà phát triển những người bạn thân nhất. Có lẽ bạn biết cách viết những nhưng sau đây là một vài mẹo.
Nếu bạn đang tham chiếu một đoạn mã nhỏ, bạn có thể nhúng đoạn mã đó trong một câu. Nếu bạn muốn trình đọc sử dụng mã, chẳng hạn như sao chép một lệnh, hãy dùng một mã chặn.
Khối mã
- Tạo nội dung ngắn gọn. Loại bỏ tất cả văn bản thừa hoặc không cần thiết khỏi mã mẫu.
- 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 các lệnh và đầu ra thành nhiều khối mã.
Định dạng mã cùng 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ã cùng dòng thay vì in nghiêng, "dấu ngoặc kép" hoặc in đậm.
- Có:
bazel help <command>: Ảnh in trợ giúp và tuỳ chọn cho<command> - Không: lệnh trợ giúp bazel: Trợ giúp về bản in và các tuỳ chọn cho "command"
- Có: