Trang này được dịch bởi Cloud Translation API.

Hướng dẫn về phong cách tài liệu TensorFlow

Thực tiễn tốt nhất

Hãy tập trung vào ý định và đối tượng người dùng.
Hãy sử dụng từ ngữ thông dụng hàng ngày và giữ cho câu ngắn gọn.
Hãy sử dụng cấu trúc câu, cách diễn đạt và cách viết hoa nhất quán.
Hãy sử dụng tiêu đề và danh sách để giúp tài liệu của bạn dễ đọc lướt hơn.
Hướng dẫn về phong cách viết tài liệu dành cho nhà phát triển của Google rất hữu ích.

Giảm giá

Với một vài ngoại lệ, TensorFlow sử dụng cú pháp Markdown tương tự như GitHub Flavored Markdown (GFM). Phần này giải thích sự khác biệt giữa cú pháp Markdown của GFM và Markdown được sử dụng cho tài liệu của TensorFlow.

Viết về mã lập trình

Các đoạn mã được đề cập trực tiếp trong mã nguồn.

Hãy đặt `backticks` xung quanh các ký hiệu sau khi sử dụng chúng trong văn bản:

Tên tham số: `input` , `x` , `tensor`
Tên tensor trả về: `output` , `idx` , `out`
Các kiểu dữ liệu: `int32` , `float` , `uint8`
Các tên toán tử khác được đề cập trong văn bản: `list_diff()` , `shuffle()`
Tên lớp: `tf.Tensor` , `Strategy`
Tên tệp: `image_ops.py` , `/path_to_dir/file_name`
Biểu thức hoặc điều kiện toán học: `-1-input.dims() <= dim <= input.dims()`

Khối mã

Sử dụng ba dấu ngoặc kép ngược để mở và đóng khối mã. Tùy chọn, chỉ định ngôn ngữ lập trình sau nhóm dấu ngoặc kép ngược đầu tiên, ví dụ:


```python
# some python code here
```

Liên kết trong Markdown và sổ tay

Các liên kết giữa các tệp trong kho lưu trữ

Sử dụng liên kết tương đối giữa các tệp trong cùng một kho lưu trữ GitHub. Bao gồm cả phần mở rộng tệp.

Ví dụ, tệp bạn đang đọc này đến từ kho lưu trữ https://github.com/tensorflow/docs . Do đó, nó có thể sử dụng đường dẫn tương đối để liên kết đến các tệp khác trong cùng kho lưu trữ như sau:

[Basics](../../guide/basics.ipynb) tạo ra Cơ bản .

Đây là phương pháp được ưu tiên vì theo cách này, các liên kết trên tensorflow.org , GitHub và Colab đều hoạt động. Ngoài ra, người đọc vẫn ở trên cùng một trang web khi họ nhấp vào liên kết.

Liên kết ngoài

Đối với các liên kết đến các tệp không có trong kho lưu trữ hiện tại, hãy sử dụng các liên kết Markdown tiêu chuẩn với URI đầy đủ. Nên ưu tiên liên kết đến URI tensorflow.org nếu có sẵn.

Để liên kết đến mã nguồn, hãy sử dụng liên kết bắt đầu bằng https://www.github.com/tensorflow/tensorflow/blob/master/ , theo sau là tên tệp bắt đầu từ thư mục gốc của GitHub.

Khi liên kết từ tensorflow.org , hãy thêm dấu ngoặc kép `` vào liên kết Markdown để hiển thị biểu tượng "liên kết ngoài".

[GitHub](https://github.com/tensorflow/docs) tạo ra GitHub

Không nên bao gồm các tham số truy vấn URI trong liên kết:

Sử dụng: https://www.tensorflow.org/guide/data
Lưu ý: https://www.tensorflow.org/guide/data?hl=en

Hình ảnh

Lời khuyên ở phần trước áp dụng cho các liên kết đến trang. Hình ảnh được xử lý khác.

Thông thường, bạn không nên tự ý đưa hình ảnh vào mã nguồn, mà thay vào đó hãy thêm nhóm TensorFlow-Docs vào yêu cầu kéo (PR) của mình và yêu cầu họ lưu trữ hình ảnh trên tensorflow.org . Điều này giúp giảm kích thước kho lưu trữ của bạn.

Nếu bạn tải hình ảnh lên kho lưu trữ của mình, hãy lưu ý rằng một số hệ thống không xử lý đường dẫn tương đối đến hình ảnh. Tốt hơn hết là sử dụng URL đầy đủ trỏ đến vị trí cuối cùng của hình ảnh trên tensorflow.org .

Liên kết đến tài liệu API

Các liên kết API sẽ được chuyển đổi khi trang web được xuất bản. Để liên kết đến trang tham chiếu API của một biểu tượng, hãy đặt đường dẫn của biểu tượng đó trong dấu ngoặc kép ngược:

`tf.data.Dataset` tạo ra tf.data.Dataset

Nên ưu tiên sử dụng đường dẫn đầy đủ, trừ trường hợp đường dẫn dài. Có thể rút gọn đường dẫn bằng cách bỏ đi các thành phần đầu tiên. Đường dẫn một phần sẽ được chuyển đổi thành liên kết nếu:

Có ít nhất một dấu . trong đường dẫn, và
Đoạn đường đi này là duy nhất trong toàn bộ dự án.

Các đường dẫn API được liên kết cho mọi dự án có API Python được công bố trên tensorflow.org . Bạn có thể dễ dàng liên kết đến nhiều dự án con từ một tệp duy nhất bằng cách đặt tên API trong dấu ngoặc kép ngược. Ví dụ:

`tf.metrics` , `tf_agents.metrics` , `text.metrics` tạo ra: tf.metrics , tf_agents.metrics , text.metrics .

Đối với các ký hiệu có nhiều bí danh đường dẫn, sẽ có một chút ưu tiên cho đường dẫn khớp với trang API trên tensorflow.org . Tất cả các bí danh sẽ chuyển hướng đến trang chính xác.

Công thức toán học trong Markdown

Bạn có thể sử dụng MathJax trong TensorFlow khi chỉnh sửa các tệp Markdown, nhưng hãy lưu ý những điều sau:

MathJax hiển thị đúng cách trên tensorflow.org .
MathJax không hiển thị đúng cách trên GitHub.
Cách ký hiệu này có thể gây khó hiểu cho các nhà phát triển chưa quen thuộc.
Để đảm bảo tính nhất quán, tensorflow.org tuân theo các quy tắc tương tự như Jupyter/Colab.

Sử dụng ký $$ xung quanh khối lệnh MathJax:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

Bao bọc các biểu thức MathJax nội tuyến bằng $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Đây là một ví dụ về biểu thức MathJax nội tuyến: $ 2 \times 2 = 4 $

Các dấu phân cách \$ ... \$ cũng hoạt động với công thức toán học nội tuyến, nhưng dạng $ đôi khi dễ đọc hơn.

Phong cách văn xuôi

Nếu bạn dự định viết hoặc chỉnh sửa những phần quan trọng của tài liệu hướng dẫn, vui lòng đọc Hướng dẫn về phong cách tài liệu dành cho nhà phát triển của Google .

Nguyên tắc về phong cách tốt

Hãy kiểm tra chính tả và ngữ pháp trong bài viết của bạn. Hầu hết các trình soạn thảo đều tích hợp công cụ kiểm tra chính tả hoặc có sẵn plugin kiểm tra chính tả. Bạn cũng có thể dán văn bản của mình vào Google Doc hoặc phần mềm soạn thảo văn bản khác để kiểm tra chính tả và ngữ pháp kỹ lưỡng hơn.
Hãy sử dụng giọng văn thân mật và thoải mái. Viết tài liệu hướng dẫn về TensorFlow như một cuộc trò chuyện – như thể bạn đang nói chuyện trực tiếp với người khác. Sử dụng giọng điệu hỗ trợ trong bài viết.

Tránh đưa ra lời phủ nhận, ý kiến cá nhân và phán xét. Những từ như "dễ dàng", "chỉ cần" và "đơn giản" chứa đựng nhiều giả định. Một việc có thể dễ dàng với bạn, nhưng lại khó khăn với người khác. Cố gắng tránh sử dụng những từ này bất cứ khi nào có thể.
Hãy sử dụng câu đơn giản, ngắn gọn, tránh dùng thuật ngữ phức tạp. Câu ghép, chuỗi mệnh đề và thành ngữ địa phương có thể khiến văn bản khó hiểu và khó dịch. Nếu một câu có thể tách thành hai câu, thì nên làm vậy. Tránh dùng dấu chấm phẩy. Sử dụng danh sách gạch đầu dòng khi thích hợp.
Cung cấp ngữ cảnh. Không sử dụng từ viết tắt mà không giải thích ý nghĩa của chúng. Không đề cập đến các dự án không thuộc TensorFlow mà không dẫn liên kết đến chúng. Giải thích lý do tại sao mã được viết theo cách đó.

Hướng dẫn sử dụng

Vận hành

Trong các tệp Markdown, hãy sử dụng # ⇒ thay vì dấu bằng đơn khi bạn muốn hiển thị giá trị trả về của một toán tử.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

Trong sổ tay, hãy hiển thị kết quả thay vì thêm chú thích (Nếu biểu thức cuối cùng trong một ô của sổ tay không được gán cho một biến, nó sẽ tự động được hiển thị).

Trong tài liệu tham khảo API, nên ưu tiên sử dụng doctest để hiển thị kết quả.

Tensor

Khi nói về tensor nói chung, không cần viết hoa chữ "tensor" . Khi nói về đối tượng cụ thể được cung cấp cho hoặc trả về từ một toán tử (op), thì bạn nên viết hoa chữ " Tensor" và thêm dấu ngoặc kép ngược xung quanh nó vì bạn đang nói về một đối tượng Tensor .

Không nên dùng từ "Tensors " (số nhiều) để mô tả nhiều đối tượng Tensor trừ khi bạn thực sự đang nói về một đối tượng Tensors . Thay vào đó, hãy nói "một danh sách (hoặc tập hợp) các đối tượng Tensor ".

Sử dụng từ " hình dạng" để mô tả chi tiết các trục của tenxơ, và thể hiện hình dạng đó trong ngoặc vuông có dấu ngoặc kép ngược. Ví dụ:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Như đã nêu ở trên, nên ưu tiên sử dụng "trục" hoặc "chỉ số" thay vì "chiều" khi nói về các thành phần của hình dạng Tensor . Nếu không, rất dễ nhầm lẫn "chiều" với chiều của không gian vectơ. Một "vectơ ba chiều" có một trục duy nhất với độ dài 3.