Cảm ơn bạn đã đóng góp cho tài liệu của Bazel. Đây là hướng dẫn nhanh về quy tắc lập trình tài liệu để giúp bạn bắt đầu. Đối với mọi câu hỏi về quy tắc chưa trả lời được trong hướng dẫn này, hãy làm theo hướng dẫn về quy tắc lập trình trong 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 của Bazel phải tuân thủ những nguyên tắc sau:
- Ngắn gọn. Sử dụng ít từ nhất có thể.
- Rõ ràng. Dùng ngôn ngữ đơn giản. Viết mà không sử dụng thuật ngữ cho cấp độ đọc lớp năm.
- Đó chính là đăng tải đều đặ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 tài liệu.
- Chính xác. Viết theo cách mà nội dung luôn chính xác trong thời gian dài nhất có thể bằng cách tránh thông tin dựa trên thời gian và lời hứa về tương lai.
Viết
Phần này bao gồm 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, chúng vừa khít với toc mà không cần bao bọc.
- Có: Quyền
- Không: Ghi chú 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 của bạn
- Không: Thiết lập không gian làm việc của bạn
Thử tạo tiêu đề dựa trên tác vụ hoặc thiết lập thành hành động. Nếu tiêu đề mang tính khái niệm, thì có thể dựa trên khả năng hiểu, nhưng hãy ghi vào nội dung mà người dùng thực hiện.
- Có: Bảo toàn thứ tự trong biểu đồ
- Không: Về việc duy trì thứ tự trong biểu đồ
Tên
Viết hoa danh từ thích hợp, như Bazel và Starlark.
- Yes (Có): Ở cuối quá trình tạo, Bazel sẽ in các mục tiêu được yêu cầu.
- No (Không): Ở cuối bản dựng, bazel sẽ in các mục tiêu được yêu cầu.
Đảm bảo sự nhất quán. Đừng đặt tên mới cho các khái niệm hiện có. Nếu có thể, 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 phát các lệnh trên một thiết bị đầu cuối, thì đừ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 đó nên được xác định ở đầu. Điều này giúp độc giả tìm thấy thông tin cần thiết 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 các trang không có hành động rõ ràng, bạn có thể thêm 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 của Bazel, đối tượng chủ yếu là người dùng – những người sử dụng Bazel để xây dựng phần mềm.
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", hãy sử dụng ngôn ngữ trung 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Ể: Để người dùng xây dựng mã Java bằng Bazel, họ 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 thông thường, hãy xác định đối tượng ở đầu trang hoặc trong phần này. 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 chuyển hoặc các vai trò khác.
Tránh dùng "chúng tôi". Trong tài liệu về người dùng, không có tác giả nào; chỉ cần cho mọi người biết những việc có thể làm.
- Yes: Khi Bazel phát triển, bạn nên cập nhật cơ sở mã của mình để 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 sẽ không tương thích và sẽ yêu cầu người dùng Bazel thực hiện một số thay đổi.
Tạm thời
Nếu có thể, hãy tránh những cụm từ định hướng mọi thứ về thời gian, chẳng hạn như đề cập đến một 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 thông tin này sẽ nhanh chóng lỗi thời và có thể không chính xác nếu đó là thông tin dự đoán trong tương lai. Thay vào đó, hãy chỉ định một 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ợ 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ể vào tháng 10 năm 2017.
Tense
Sử dụng thì hiện tại. Tránh thì quá khứ hoặc tương lai trừ phi thực sự cần thiết để đảm bảo sự rõ ràng.
- Yes (Có): Bazel báo lỗi khi tìm thấy các phần phụ thuộc không tuân theo 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ẽ báo lỗi.
Nếu có thể, hãy sử dụng giọng nói chủ động (trong đó một chủ thể hoạt động trên một đối tượng) thay vì giọng nói bị động (khi một đối tượng tác động lên một đối tượng). Nhìn chung, giọng nói chủ động sẽ giúp các câu trở nên rõ ràng hơn vì nó cho biết ai là người chịu trách nhiệm. Nếu việc sử dụng giọng nói chủ động làm giảm sự rõ ràng, hãy sử dụng giọng bị động.
- Yes (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 bằng dữ liệu đầu ra.
Giọng điệu
Viết bài với giọng điệu thân thiện với doanh nghiệp.
Tránh sử dụng ngôn từ tục tĩu. Khó dịch các cụm từ dành riêng cho tiếng Anh.
- Có: Bộ quy tắc hợp lệ
- Không: Vậy bộ quy tắc hiệu quả là gì?
Tránh ngôn từ quá trang trọng. Viết như thể bạn đang giải thích về khái niệm này 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 ở mức 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
Hãy sử dụng văn bản đường liên kết mang tính mô tả thay vì "ở đây" hoặc "bên dưới". Phương pháp 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 [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ày, nếu có thể.
- Có: Để biết thêm chi tiết, hãy xem [đường liên kết].
- 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 nhiệm vụ kèm theo các bước
- Sử dụng một danh sách không theo thứ tự để liệt kê những mục không dựa trên nhiệm vụ. (Vẫn cần có thứ tự phân loại, chẳng hạn như thứ tự bảng chữ cái, mức độ quan trọng, v.v.)
- Viết với cấu trúc song song. Ví dụ:
- Tạo tất cả các câu cho mục trong danh sách.
- Bắt đầu với động từ có cùng thì.
- Sử dụng danh sách theo 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 sẽ 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>: Trợ giúp về ảnh in và các tuỳ chọn cho<command> - Không: lệnh trợ giúp bazel: Trợ giúp in và các tuỳ chọn cho "command" (lệnh)
- Có:
Đặc biệt là đối với các mã mẫu phức tạp, hãy sử dụng phần giữ chỗ có ý nghĩa theo ngữ cảnh.
Mục lục
Sử dụng toc được tạo tự động mà trang web hỗ trợ. Đừng thêm nội dung theo cách thủ công.
Mã
Mã mẫu là người bạn thân thiết nhất của các nhà phát triển. Có thể bạn đã biết cách viết những nội dung này, 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ã này, chẳng hạn như sao chép 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 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 các khối mã khác nhau.
Đị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>: Trợ giúp về ảnh in và các tuỳ chọn cho<command> - Không: lệnh trợ giúp bazel: Trợ giúp in và các tuỳ chọn cho "command" (lệnh)
- Có: