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