最佳实践
- 关注用户意图和受众。
- 使用日常用语，并保持句子简短。
- 使用一致的句子结构、措辞和大小写。
- 使用标题和列表使您的文档更易于浏览。
- Google 开发者文档风格指南 很有帮助。
Markdown
除了少数例外，TensorFlow 使用与 GitHub Flavored Markdown (GFM) 类似的 Markdown 语法。本节介绍 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://tensorflowcn.cn/guide/data">https://tensorflowcn.cn/guide/data</a> - 不要使用：
<a href="https://tensorflowcn.cn/guide/data?hl=en">https://tensorflowcn.cn/guide/data?hl=en</a>
图像
上一节中的建议适用于指向页面的链接。图像的处理方式不同。
通常，您不应该签入图像，而是将您的 PR 添加到 TensorFlow-Docs 团队，并要求他们在 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 来显示结果。
张量
当您一般谈论张量时，不要将张量一词大写。当您谈论提供给操作或从操作返回的特定对象时，您应该将张量一词大写并在其周围添加反引号，因为您正在谈论一个 张量 对象。
除非您真的在谈论一个 张量 对象，否则不要使用张量（复数）一词来描述多个 张量 对象。相反，说“一个 张量 对象列表（或集合）”。
使用形状一词来详细说明张量的轴，并在方括号中使用反引号显示形状。例如
If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.
如上所述，在谈论 张量 形状的元素时，建议使用“轴”或“索引”而不是“维度”。否则很容易将“维度”与向量空间的维度混淆。“三维向量”只有一个长度为 3 的轴。