Use the following style guide to ensure the Terra documentation is understandable, useful, consistent, and organized.
The Terra Docs are:
Write in a personable voice with a positive attitude.
Use the same terminology, formatting, voice, and tone across all your documentation. Markdown takes the guesswork out of formatting. Use the conventions in this guide to maintain consistency.
The Terra Docs are intended for a diverse, international audience. Use natural language, and talk like a person. Avoid technical jargon and obscure words. Use your writing to present Terra. Don't use Terra to present your writing.
Write less. Say more.
Simplicity is at the heart of the Terra style. Writers and readers will understand each other better with a minimalist approach. Emphasize clarity over complexity.
Writing in shorter sentences will give your writing more clarity. Try to limit the number of clauses in a sentence. Simplify your language. Avoid jargon.
All people are welcome here. Use appropriate language as it relates to matters of identity.
For more information, see the Microsoft bias-free writing guidelines.
The Terra Docs are structured using the Diataxis framework. Each document should fall into one of the four categories: tutorials, how-to guides, explanation, and reference. Try not to overlap categories in the same document.
Tutorials start the user from scratch and walk them through the process of getting started. Discussion should be kept to a minimum in these guides. Action is important. Tutorials walk the user through a complete, concrete series of steps to achieve a goal.
Example: The Terrain initial setup
These guides are shorter than tutorials and explain how to do different actions after the user has gone through a tutorial. How-to guides don't start from scratch.
Example: Start the LCD
Explanations are discussions that explain a particular topic.
Example: What is Terra?
Informational material used for quick reference.
Example: The Terrad commands and subcommands
All writing in the Terra Docs is written in the second or third person.
First-person language such as "I," "we," "us," or "let's" should be avoided in all situations.
Examples:
- "We recommend," becomes "it is recommended."
- "Let's use the following command," becomes "use the following command."
- "Our project," becomes "your project."
Use the spelled-out term followed by the acronym in parentheses, such as dynamic-link library (DLL). On subsequent occurrences in the same topic, use the acronym.
Italics should be avoided. Bold is used in the following cases:
- When referring to interface buttons. "Click Send."
- When denoting examples.
Ending punctuation is never stylized or included in links.
Example: Open the window and click Next. Select a fee to submit a transaction.
Code should be in blocks. A command that a user needs to execute should be written in a code block rather than inline. Use inline code to refer to specific parts of code.
Example: Use the start command to run the application:
npm startUse notes in code blocks sparingly, if at all. Most notes should be written above the code block. Annotations should be reserved for long code blocks.
Code blocks in tutorials should be written so that a user can copy and paste them directly into their terminal using the copy button on each code block.
Avoid using multiple commands in a code block. Commands should be separated and listed as substeps.
Code mentioned outside of code blocks should always be written in tick marks exactly as it appears.
Code Hike syntax for inline code:
_`inline code`_
Example:
Use the k.FunctionExapmle function to create an example.
Avoid starting sentences with code, as it makes capitalization and punctuation difficult. Never alter the punctuation or capitalization of code. Write it exactly as it appears.
Example:
All code goes inside tick marks, even when referring to specific variables.
Dropdowns can be used to hide content that is related but not necessary to the page.
<details>
<summary> Title </summary>
<p>
```
hidden content
```
</p>
</details>
Examples are denoted using the following format:
**Example**: You can put a short intro to the example here.
This is an example.
Name all your files and folders using lower case. Use dashes if necessary. Do not use spaces or underscores. Keep filenames succinct.
Example:
my-folder/my-file.png
Markdown takes the guesswork out of formatting. Rely on Markdown to format and standardize your documentation. Do not use special HTML code to format text. The point of Markdown is to be consistent. Do not use breaks <br/> unless absolutely necessary. Avoid using lines to denote sections. Headings denote sections.
Limiting your styling will make your writing clearer and more succinct.
Headings denote sections in a document. Each page should contain only one first-level heading as its title. Headings below the title can be nested. Do not skip heading levels.
Headings that denote chronological steps are numbered. Headings used to denote non-chronological sections, such as explanations or stand-alone information, are not numbered.
All headings follow sentence-style capitalization. Avoid starting a heading with in-line code. Headings should not have ending punctuation, except for questions.
Level 1 headings should only be used for titles.
Try to use only three heading levels. Do not use more than 4 levels.
Example:
# Title heading only
## Level 2
### Level 3
#### Avoid using level 4 headings
##### Never use more than 4 levels
Use the Markdown syntax for images whenever possible. Avoid using HTML to customize images.
All images should be named with a short, descriptive label.
Example:
Use descriptive text for links. Avoid using "here" as a placeholder. All links are written in markdown format.
Example:
Incorrect: For more examples, click here.
Correct: For more examples, visit the example page.
Descriptive links help the user understand where they are going.
-
Any steps that need to be completed sequentially are ordered.
-
Ordered lists must contain at least two steps.
- Use unordered lists to list non-sequential information.
- Use sentence-style capitalization and punctuation in unordered lists.
- Unordered lists must contain at least two components.
You can use admonitions by importing them and using the following syntax:
import Admonition from '@theme/Admonition';
<Admonition type="note" icon="📝" title="Your Title">
Some **content** with _markdown_ `syntax`.
</Admonition>
Admonition types:
note
tip
info
caution
danger
All notes, warnings, tips, or other admonitions must be written in an admonition box. Don't use subtext or other formatting elements. If a note is important, it goes in a box. If it is not important, leave it out.
Try to use custom titles for all admonitions.
Example:
<Admonition type='note' icon="📝" title=`Writing admonitions'
Admonitions are brief and direct. They provide important information to the user. Don't overuse admonitions.
</Admonition>
Numbers below ten should be spelled out when used in a sentence. When referring to a specific step number, just use the numeral. Proper nouns or direct references don't need to be spelled out.
Example:
"There are three things to remember."
"There are 40 things to remember."
"Go to step 2."
"Pisco-2"
"Step 9 shows how to start the LCD."
Simplify your writing. While tempting, em dashes and parentheticals promote unnecessary complexity and ambiguous grammar.
Use the Oxford comma.
Punctuation integral to a sentence should never be styled or included in a link.
Examples:
Period outside of link:
"Visit the [example page](example.com). "
Commas outside of code:
The three commands are `start`, `end`, and `help`.