Best practices
- Focus on user intent and audience.
- Use every-day words and keep sentences short.
- Use consistent sentence construction, wording, and capitalization.
- Use headings and lists to make your docs easier to scan.
- The Google Developer Docs Style Guide is helpful.
Markdown
With a few exceptions, TensorFlow uses a Markdown syntax similar to GitHub Flavored Markdown (GFM). This section explains differences between GFM Markdown syntax and the Markdown used for TensorFlow documentation.
Write about code
Inline mentions of code
Put `backticks`
around the following symbols when used in
text:
- Argument names:
`input`
,`x`
,`tensor`
- Returned tensor names:
`output`
,`idx`
,`out`
- Data types:
`int32`
,`float`
,`uint8`
- Other op names reference in text:
`list_diff()`
,`shuffle()`
- Class names:
`tf.Tensor`
,`Strategy`
- File name:
`image_ops.py`
,`/path_to_dir/file_name`
- Math expressions or conditions:
`-1-input.dims() <= dim <= input.dims()`
Code blocks
Use three backticks to open and close a code block. Optionally, specify the programming language after the first backtick group, for example:
```python
# some python code here
```
Links in Markdown
Links between files in this repository
Use relative links between files in a repository. This works on
tensorflow.org and
GitHub:
[Custom layers](../tutorials/eager/custom_layers.ipynb)
produces
Custom layers on the
site.
Links to API documentation
API links are converted when the site is published. To link to a symbol's API reference page, enclose the full symbol path in backticks:
`tf.data.Dataset`
producestf.data.Dataset
For the C++ API, use the namespace path:
tensorflow::Tensor
produces tensorflow::Tensor
External links
For external links, including files on https://www.tensorflow.org
that are not in the tensorflow/docs
repository, use standard Markdown links
with the full URI.
To link to source code, use a link starting with https://www.github.com/tensorflow/tensorflow/blob/master/, followed by the file name starting at the GitHub root.
This URI naming scheme ensures that https://www.tensorflow.org can forward the link to the branch of the code corresponding to the version of the documentation you're viewing.
Do not include URI query parameters in the link.
File paths use underscores for spaces, for example, custom_layers.ipynb
.
Include the file extension in links to use on the site and GitHub, for example,
[Custom layers](../tutorials/eager/custom_layers.ipynb)
.
Math in Markdown
You may use MathJax within TensorFlow when editing Markdown files, but note the following:
- MathJax renders properly on tensorflow.org.
- MathJax does not render properly on GitHub.
- This notation can be off-putting to unfamiliar developers.
- For consistency tensorflow.org follows the same rules as Jupyter/Colab.
Use $$
around a block of MathJax:
$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$
Wrap inline MathJax expressions with $ ... $
:
This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $
This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $
\\( ... \\)
delimiters also work for inline math,
but the $ form is sometimes more readable.
Prose style
If you are going to write or edit substantial portions of the narrative documentation, please read the Google Developer Documentation Style Guide.
Principles of good style
- Check the spelling and grammar in your contributions. Most editors include a spell checker or have an available spell-checking plugin. You can also paste your text into a Google Doc or other document software for a more robust spelling and grammar check.
- Use a casual and friendly voice. Write TensorFlow documentation like a conversation—as if you're talking to another person one-on-one. Use a supportive tone in the article.
- Avoid disclaimers, opinions, and value judgements. Words like "easily", "just", and "simple" are loaded with assumptions. Something might seem easy to you, but be difficult for another person. Try to avoid these whenever possible.
- Use simple, to the point sentences without complicated jargon. Compound sentences, chains of clauses, and location-specific idioms can make text hard to understand and translate. If a sentence can be split in two, it probably should. Avoid semicolons. Use bullet lists when appropriate.
- Provide context. Don't use abbreviations without explaining them. Don't mention non-TensorFlow projects without linking to them. Explain why the code is written the way it is.
Usage guide
Ops
In markdown files, use # ⇒
instead of a single equal sign when you want to
show what an op returns.
# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0) # ⇒ [1, 2, 3, 5]
In notebooks, display the result instead of adding a comment (If the last expression in a notebook cell is not assigned to a variable, it is automatically displayed.)
In API reference docs prefer using doctest to show results.
Tensors
When you're talking about a tensor in general, don't capitalize the word
tensor. When you're talking about the specific object that's provided to or
returned from an op, then you should capitalize the word Tensor and add
backticks around it because you're talking about a Tensor
object.
Don't use the word Tensors (plural) to describe multiple Tensor
objects
unless you really are talking about a Tensors
object. Instead, say "a list (or
collection) of Tensor
objects".
Use the word shape to detail the axes of a tensor, and show the shape in square brackets with backticks. For example:
If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.
As above, prefer "axis" or "index" over "dimension" when talking about the
elements of a Tensor
's shape. Otherwise it's easy to confuse "dimension" with
the dimension of a vector space. A "three-dimensional vector" has a single axis
with length 3.