Hướng dẫn về quy tắc lập trình tài liệu của Bazel

Báo cáo vấn đề Xem nguồn Nightly · 8.0 . 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Cảm ơn bạn đã đóng góp cho tài liệu của Bazel. Đây là hướng dẫn nhanh về phong cách tài liệu để giúp bạn bắt đầu. Đối với mọi câu hỏi về văn phong mà hướng dẫn này không giải đáp được, hãy làm theo Hướng dẫn văn phong 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 càng ít từ càng tốt.
  • Xoá. Sử dụng ngôn ngữ đơn giản. Viết mà không dùng từ chuyên môn cho cấp độ đọc lớp 5.
  • 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 tài liệu.
  • Đúng. Viết nội dung theo cách 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 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.)

  • Tiêu đề càng ngắn càng tốt. Bằng cách này, các mục này sẽ vừa với mục lục mà không cần gói.

    • 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
    • Không: Thiết lập Workspace

  • Cố gắng tạo tiêu đề dựa trên việc cần làm hoặc có thể hành động. 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ó: 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ó: Khi quá trình xây dựng kết thúc, Bazel sẽ in các mục tiêu đã yêu cầu.
    • Không: Ở 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 đặt tên mới cho các khái niệm hiện có. Khi 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ề cách đưa ra 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à mục đích đó phải được xác định ngay từ đầu. Điều này giúp độc giả nhanh chóng tìm thấy nội dung mình cầ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 mở đầ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 đườ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 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 đó mà bạn không thể sử dụng từ "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 dùng đại 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ững gì có thể làm được.

    • 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, các 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.

Tạm thời

Nếu có thể, hãy tránh những từ ngữ định hướng 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 "bây giờ", "hiện tại" hoặc "sắp tới". Những dữ liệu này nhanh chóng lỗi thời và có thể không chính xác nếu đó là dữ liệu 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ợ 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 tương lai trừ phi cần thiết để làm rõ.

    • Có: Bazel sẽ báo lỗi khi phát hiện các phần phụ thuộc không tuân thủ quy tắc này.
    • Không: Nếu phát hiện một phần phụ thuộc không tuân thủ quy tắc này, Bazel sẽ báo lỗi.

  • Khi có thể, hãy sử dụng giọng chủ động (trong đó chủ thể tác động lên đối tượng) chứ không phải giọng bị động (trong đó đối tượng chịu tác động của chủ thể). Nhìn chung, giọng chủ động giúp câu văn rõ ràng hơn vì cho biết ai là người chịu trách nhiệm. Nếu việc sử dụng giọng chủ động làm giảm tính rõ ràng, hãy sử dụng giọng bị động.

    • Có: Bazel khởi tạo 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 đầu ra.

Giọng điệu

Viết bằng giọng điệu phù hợp với doanh nghiệp.

  • Tránh sử dụng ngôn từ thông tục. Khó dịch các cụm từ chỉ dành riêng cho tiếng Anh.

    • Có: Quy tắc tốt
    • Không: Vậy quy tắc tốt là gì?

  • Tránh sử dụng ngôn từ quá trang trọng. Viết như thể bạn đang giải thích 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 ngắt dòng ở 80 ký tự. Đường liên kết dài hoặc đoạn mã có thể dài hơn, nhưng phải bắt đầu ở một dòng mới. Ví dụ:

  • Sử dụng văn bản mô tả đường liên kết thay vì "tại đây" hoặc "dưới đây". Phương pháp này giúp bạn dễ dàng quét tài liệu hơn và phù hợp hơn với trình đọc màn hình.

    • Có: Để biết thêm thông tin chi tiết, hãy xem bài viết [Cài đặt Bazel].
    • Không: Để biết thêm thông tin 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 thông tin chi tiết, hãy xem [đường liên kết].
    • 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 đã sắp xếp để 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 theo thứ tự để liệt kê những thứ không dựa trên tác vụ. (Vẫn phải có thứ tự sắp xếp, chẳng hạn như theo thứ tự bảng chữ cái, mức độ quan trọng, v.v.)
  • Viết bằng cấu trúc song song. Ví dụ:
    1. Tạo tất cả các mục trong danh sách thành câu.
    2. Bắt đầu với các động từ có cùng thì.
    3. 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 hướng dẫn và các tuỳ chọn cho <command>
    • Không: bazel help command: In thông tin trợ giúp và các tuỳ chọn cho "command"

  • Đặc biệt đối với các mẫu mã phức tạp, hãy sử dụng phần giữ chỗ phù hợp với ngữ cảnh.

Mục lục

Sử dụng mục lục được tạo tự động mà trang web hỗ trợ. Không thêm mục lục theo cách thủ công.

Mã

Mẫu mã là người bạn thân nhất của nhà phát triển. Có thể bạn đã biết cách viết các hàm 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 trình đọ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ẫ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 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>: In hướng dẫn và các tuỳ chọn cho <command>
    • Không: bazel help command: In thông tin trợ giúp và các tuỳ chọn cho "command"