## Heading
```
## Introduction
Introductory paragraphs describe the purpose of the document. Introductions usually include:
- **Objectives**: The goals for the document and the purpose of the feature
- **Descriptions**: A brief description of the product, feature, tool or service, and location
- **Scope**: Defines the target audience, and any limitations of the content
- **Prerequisites**: Any required or useful context
- **References**: Links to TritonDataCenter references and other relevant information
### Example introductions
This sample introductory paragraph is from a CloudOps SOP:
*Ceres is a Linux container management system developed by the PI team in the Cloud Platform Group. Ceres was developed on a customized Mesos and framework for managing both long-running services and batch jobs for an on-premise infrastructure. Ceres machines are located in one or two racks of Dell R730 servers per data center. CloudOps monitors the hardware, and the Samsung Cloud Platform Group (CPG) manages the operating system install and application runs.*
*This document describes the general process of building Ceres on the admin servers. It does not describe how to conduct the build. The Ceres build can take more than 20 hours and requires that CloudOps coordinate schedules and plan for outages.*
For more examples of introductory paragraphs, visit the following links:
- [Starting and managing virtual machine instances](https://docs.tritondatacenter.com/public-cloud/instances/virtual-machines/managing)
- [Triton CLI tool](https://docs.tritondatacenter.com/public-cloud/api/triton-cli)
- [Manta: Triton's object storage and converged analytics solution](https://apidocs.tritondatacenter.com/manta/)
## Headings
The body content begins with a second level heading. First level-headings, prefaced by a single hash mark, are reserved for the page title. Format tips to keep in mind:
1. The first-level heading Markdown `# ` is reserved for the title of the page. The page content begins with a second-level level heading `## `.
1. Use headers for separating sections of content, not bold text.
1. There is no line break between the header and the first line of content.
1. There is one line break between the last sentence of a section and the next heading.
## Body content
The body content varies according to the goals of the document. In general, content pages have three types of content: tasks, concepts, and references.
### Tasks
Tasks are organized into steps that describe a sequence of actions that the user must take to accomplish a goal. See [Getting started](https://docs.tritondatacenter.com/public-cloud/getting-started) and [Manually generating your SSH key in macOS [https://docs.tritondatacenter.com/public-cloud/getting-started/ssh-keys/generating-an-ssh-key-manually/manually-generating-your-ssh-key-in-mac-os-x] for examples of task-based content.
### Concepts
Concept pages explain how things work or what they mean to the user. One example of a conceptual page is the [Containers and virtual machines](https://docs.tritondatacenter.com/public-cloud/instances) document.
### References
Reference pages contain quick look ups with additional detail. See [Work with Docker containers](https://docs.tritondatacenter.com/public-cloud/instances/docker/how) and [Using the metdata API](https://docs.tritondatacenter.com/private-cloud/instances/using-mdata) for examples of reference pages.
### Useful information
It is always useful to provide an overview of current state of features such as:
- **Functionality**. What can the product, feature, tool or service do and how?
- **Stability**. Is it HA, Reliability, Production-Grade Dependency?
- **Reliablity**. What conditions may cause the product, feature, tool or service to fail?
- **Known errors**. Lists of known or expected errors or issues. (Graceful w/ error or hard (no error, tough to debug)
- **Performance**. What considerations should you take at the extremes? (high concurrency, network/disk io, cpu/memory constraints, data/size constraints, etc.)
- **Supported**. The version. Is the product, feature, tool or service in alpha, beta, or considered production released / LTS?
- **Change logs**. Include or link to relevant change logs, such as 1st release notes, 2nd release notes, versioning, dates
- **Usage examples**. Provide examples separated by use case (cloud api, operator api, gui)
- **Procedures**. Include sequential, how-to information.
## Images
Images can help illustrate the concepts that you are describing. Make sure the graphics are useful—most users don't require visual represntation of an interface unless the feature is counterintuitive or difficult to understand. Images should not be placed in code blocks.
You can insert an image on the page using the `(image)` tag. There are three classes related to image size: `full`, `onehalf`, and `onethird`. This example code specifies the `onehalf` class and includes `alt` text.
```
(image: image.jpg alt: Picture of an eagle fishing class: onehalf)
```
The image renders similar to this example:
**Important:** Please only use images that are included in the current page content folder. This may occasionally result in duplicating an image from another page, but that's better than having images break on reorganization.
Always include alt text for accessibility.
[Learn more about image file rules](https://docs.tritondatacenter.com/writing-rules/using-kirby#image-files).
## Links
A best practice to use the official Kirby method for links. Although the official Markdown way to include links works on our sites, using Kirby makes it easy to add both custom text, CSS classes, and popups. The following list example includes the links side-by-side with the generation code.
| Example | Markdown |
|:-|:-|
| tritondatacenter.com | `(link: http://www.tritondatacenter.com)` |
| TritonDataCenter's website | `(link: http://www.tritondatacenter.com text: TritonDataCenter's website)` |
| Popup for TritonDataCenter's website | `(link: http://www.tritondatacenter.com text: TritonDataCenter's website popup: yes)` |
| TritonDataCenter's website | `(link: http://www.tritondatacenter.com text: TritonDataCenter's website class: website-class)` |
| info@tritondatacenter.com | `(email: info@tritondatacenter.com)` |
If linking to content from tritondatacenter.com within our documentation, you must include the full URL, i.e. `(link: https://tritondatacenter.com/blog/nodejs-9-release-summary)`.
## Videos
Video is uploaded to TritonDataCenter's Vimeo account and included via the following markdown:
```
(vimeo: //vimeo.com/)
```
Pages with video content include:
- [Getting started](https://docs.tritondatacenter.com/public-cloud/getting-started)
- [Starting and managing] (https://docs.tritondatacenter.com/public-cloud/instances/infrastructure/managing)
## Code
Code examples provide users with concrete examples. When possible, blocks of code should be [included as text, wrapped with backticks and a code highlighting hint](https://help.github.com/articles/creating-and-highlighting-code-blocks/).
```
This is a GitHub code fence.
```
Right now you can use any of the following language specifiers with your backticks:
- javascript
- js
- bash
- shell
If you don't specify anything, the code block is left alone. You can also use the specifier `prettyprint` and the highlighter will take its best guess.
## Variables
Here are some common variables for code examples.
+ ``
+ ``
+ `` (for container name or UUID)
## Tables
Tables organize and convey complex information.Pages with tables include:
- [Tags and metadata](https://docs.tritondatacenter.com/public-cloud/tags-metadata)
- [Triton hardware](https://docs.tritondatacenter.com/private-cloud/hardware)
Table markdown example:
```
| Term | Meaning |
| :---- | :---- |
| ANY | Any machine anywhere on the Internet |
| ALL VMS | All instances on this data center that have the Cloud Firewall feature enabled. |
```
The colons specify the alignment of the headings. In this example, the text is left-aligned:
| Term | Meaning |
| :---- | :---- |
| ANY | Any machine anywhere on the Internet |
| ALL VMS | All instances on this data center that have the Cloud Firewall feature enabled. |
The [Sublime table editor page](https://github.com/vkocubinsky/SublimeTableEditor) provides several useful examples of Markdown table code. If you are building a large table, consider using an [automatic table generator](https://www.tablesgenerator.com/markdown_tables) to save time building and formatting in Markdown.
## What are my next steps?
Many pages direct the user to logical next steps. For examples of Next Step sections, visit the [Getting started](https://docs.tritondatacenter.com/public-cloud/getting-started) and the [Triton CLI](https://docs.tritondatacenter.com/public-cloud/api/triton-cli) pages.
Once you have read this template page and have a plan for structuring your documents, visit the following pages for more information:
- [Writing for Kirby](https://docs.tritondatacenter.com/writing-rules/using-kirby)
- [Working with GitHub repos](https://docs.tritondatacenter.com/writing-rules/repos)
- [TritonDataCenter style guide](https://docs.tritondatacenter.com/writing-rules/style-guide#when-in-doubt-don%E2%80%99t-capitalize)
- [Triton compute glossary](https://docs.tritondatacenter.com/glossary)
