最佳做法
- 專注於使用者意圖和目標對象。
- 使用日常用語並保持句子簡短。
- 使用一致的句子結構、措辭和大小寫。
- 使用標題和清單讓您的文件更容易掃描。
- 《Google 開發人員文件樣式指南》很有幫助。
Markdown
TensorFlow 使用的 Markdown 語法與GitHub Flavored Markdown (GFM) 類似，但有一些例外。本節說明 GFM Markdown 語法與 TensorFlow 文件使用的 Markdown 之間的差異。
撰寫程式碼相關內容
程式碼的內嵌提及
當在文字中使用下列符號時，請在符號周圍加上 `反引號`
- 引數名稱：
`input`、`x`、`tensor` - 傳回的張量名稱：
`output`、`idx`、`out` - 資料類型：
`int32`、`float`、`uint8` - 文字中參考的其他運算名稱：
`list_diff()`、`shuffle()` - 類別名稱：
`tf.Tensor`、`Strategy` - 檔案名稱：
`image_ops.py`、`/path_to_dir/file_name` - 數學運算式或條件：
`-1-input.dims() <= dim <= input.dims()`
程式碼區塊
使用三個反引號來開啟和關閉程式碼區塊。您可以選擇在第一個反引號群組後指定程式語言，例如
```python
# some python code here
```
Markdown 和筆記本中的連結
儲存庫中檔案之間的連結
在單一 GitHub 儲存庫中使用檔案之間的相對連結。請加入副檔名。
例如，您正在閱讀的這個檔案來自 https://github.com/tensorflow/docs 儲存庫。因此，它可以像這樣使用相對路徑連結到同一儲存庫中的其他檔案
[Basics](../../guide/basics.ipynb)產生 Basics。
這是建議的方法，因為這樣一來，tensorflow.org、GitHub 和 Colab 上的連結都能運作。此外，讀者在點擊連結時會停留在同一個網站中。
外部連結
對於不在目前儲存庫中的檔案連結，請使用具有完整 URI 的標準 Markdown 連結。如果有的話，請優先連結到 tensorflow.org URI。
若要連結到原始碼，請使用以 https://www.github.com/tensorflow/tensorflow/blob/master/ 開頭的連結，後面接著從 GitHub 根目錄開始的檔案名稱。
從 tensorflow.org 連結出去時，請在 Markdown 連結中加入 {:.external}，以便顯示「外部連結」符號。
[GitHub](https://github.com/tensorflow/docs){:.external}產生 GitHub
請勿在連結中加入 URI 查詢參數
- 使用：
<a href="https://tensorflow.dev.org.tw/guide/data">https://tensorflow.dev.org.tw/guide/data</a> - 而非：
<a href="https://tensorflow.dev.org.tw/guide/data?hl=en">https://tensorflow.dev.org.tw/guide/data?hl=en</a>
圖片
前一節中的建議適用於頁面的連結。圖片的處理方式不同。
一般來說，您不應簽入圖片，而是將 TensorFlow 文件團隊新增至您的 PR，並要求他們將圖片託管在 tensorflow.org 上。這有助於縮減儲存庫的大小。
如果您確實將圖片提交到您的儲存庫，請注意某些系統不處理圖片的相對路徑。最好使用指向圖片在 tensorflow.org 上最終位置的完整 URL。
API 文件連結
API 連結會在網站發佈時轉換。若要連結到符號的 API 參考頁面，請將符號路徑放在反引號中
`tf.data.Dataset`產生tf.data.Dataset
除了長路徑之外，稍微偏好完整路徑。路徑可以透過捨棄開頭路徑元件來縮寫。如果符合下列條件，部分路徑將會轉換為連結
- 路徑中至少有一個
.，且 - 部分路徑在專案中是唯一的。
API 路徑會針對每個在 tensorflow.org 上發佈 Python API 的專案連結。您可以透過將 API 名稱加上反引號，輕鬆地從單一檔案連結到多個子專案。例如
`tf.metrics`、`tf_agents.metrics`、`text.metrics`產生：tf.metrics、tf_agents.metrics、text.metrics。
對於具有多個路徑別名的符號，稍微偏好與 tensorflow.org 上的 API 頁面相符的路徑。所有別名都會重新導向到正確的頁面。
Markdown 中的數學式
您可以在編輯 Markdown 檔案時在 TensorFlow 中使用 MathJax，但請注意下列事項
- MathJax 在 tensorflow.org 上正確呈現。
- MathJax 在 GitHub 上無法正確呈現。
- 此標記法可能會讓不熟悉的開發人員反感。
- 為了保持一致性，tensorflow.org 遵循與 Jupyter/Colab 相同的規則。
在 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 \]
使用 $ ... $ 包裝內嵌 MathJax 運算式
This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $
以下是內嵌 MathJax 運算式的範例：\( 2 \times 2 = 4 \)
\\( ... \\) 分隔符號也適用於內嵌數學式，但 $ 形式有時更易於閱讀。
散文風格
如果您要撰寫或編輯敘述性文件的大部分內容，請閱讀《Google 開發人員文件樣式指南》。
良好風格的原則
- 檢查您貢獻內容中的拼字和文法。 大多數編輯器都包含拼字檢查器，或具有可用的拼字檢查外掛程式。您也可以將文字貼到 Google 文件或其他文件軟體中，以進行更完善的拼字和文法檢查。
- 使用隨性友善的語氣。 撰寫 TensorFlow 文件時，就像在對話一樣，彷彿您正在與另一個人一對一交談。在文章中使用支持性的語氣。
- 避免免責聲明、意見和價值判斷。 「輕鬆」、「僅僅」和「簡單」等詞語帶有許多假設。對您來說可能很容易的事情，對另一個人來說可能很困難。盡可能避免使用這些詞語。
- 使用簡單、切入重點的句子，避免使用複雜的術語。 複合句、子句鏈和特定地點的慣用語可能會使文字難以理解和翻譯。如果一個句子可以分成兩個句子，則可能應該這樣做。避免使用分號。在適當時使用項目符號清單。
- 提供背景資訊。 請勿在沒有解釋的情況下使用縮寫。請勿在沒有連結到非 TensorFlow 專案的情況下提及它們。說明程式碼為何以這種方式撰寫。
用法指南
運算
在 markdown 檔案中，當您想要顯示運算傳回的內容時，請使用 # ⇒ 而不是單一等號。
# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0) # ⇒ [1, 2, 3, 5]
在筆記本中，顯示結果而不是新增註解 (如果筆記本單元格中的最後一個運算式未指派給變數，則會自動顯示。)
在 API 參考文件中，最好使用 doctest 來顯示結果。
張量
當您一般談論張量時，請勿將「張量」一詞大寫。當您談論提供給運算或從運算傳回的特定物件時，則應將「張量」一詞大寫，並在其周圍加上反引號，因為您談論的是 Tensor 物件。
除非您真的在談論 Tensors 物件，否則請勿使用「張量」(複數) 一詞來描述多個 Tensor 物件。請改為說「Tensor 物件的清單 (或集合)」。
使用「形狀」一詞來詳細說明張量的軸，並以方括號和反引號顯示形狀。例如
If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.
如上所述，當談論 Tensor 形狀的元素時，最好使用「軸」或「索引」而不是「維度」。否則，很容易將「維度」與向量空間的維度混淆。「三維向量」具有長度為 3 的單一軸。