Page title
27 days ago
The opening paragraph should be used to succinctly explain to the reader what value the concept or feature provides and what use cases it supports. If possible, display the use cases in a bullet list.
Introduction
Use the introduction to explain more about the feature/task, what it is for, why it is useful, and the wider context. Try to answer the following questions for the reader:
-
Why should I be interested in this task?
-
How will this task help me create more value in my usage of CircleCI?
You might want to include an image or diagram here to help illustrate more complex concepts. The docs team can work with you to help create helpful image to support explanatory information:
Quickstart
Some readers will want to read through a full overview page to get a deep understanding of how a feature works, including:
-
The full set of options available to them.
-
Any limitations that might apply to them, or parts of the usage or setup process with the potential to catch them out.
-
Find troubleshooting information.
Others will want to get started with the feature or task right away and then return to the docs as needed. For those that want to get stuck in right away, it is a good idea to provide a quickstart section.
You have two options here:
-
Point readers to a how-to guide if available.
-
Provide minimal ordered steps to get set up:
-
Provide some steps here.
-
To get started with this feature.
-
Include a step for every action.
-
Do not skip steps or assume readers will know, for example, which button to select.
How the feature works
Provide some detail on how the feature works 'under the hood' so readers can better conceptualise what they are doing. You might want to break this down into subsections.
Subsection title
Break up large blocks of text where possible to help make it easier to consume. You can use bullet lists:
-
Item 1
-
Item 2
-
Item 3
Using tables
This section shows how to create a table. This example has one heading row and one regular row. The table has three columns, and the third column is twice as wide as the first two columns. THe table has a title.
| Header text column 1 | Header text column 2 | Header text column 3 |
|---|---|---|
Text for row 1 column 1 |
Text for row 1 column 2 |
Text for row 1 column 3 |
For a full description of the options available, including merging cells, and cell formatting, see the Asciidoctor docs.
Links and cross references
To link out to content outside of the docs use a link:
To link to another page within the docs use a cross reference:
You can place the subsection anchor using a hash symbol if you want to link to a subsection:
Code examples
Use AsciiDoc source blocks for code examples, with a title where possible. Use comments in the code block to explain what is happening:
version: 2.1
jobs:
build:
docker: # use a docker image to run the job
- image: cimg/base:2021.04
steps:
- checkout # check out the code in the project directory
- run:
name: The First Step
command: |
echo 'Hello World!'
echo 'This is the delivery pipeline'
- run:
name: The Second Step
command: |
ls -al
echo '^^^The files in your repo^^^'Banners
Use admonitions to create blocks of content that stand out from the main flow of text. Use admonitions sparingly as they can be distracting or lose emphasis if they appear too often. Currently we have the option to include tips notes, cautions, and warnings, as follows:
| Need to add a tip? This is how to do it |
| Need to add a note? This is how to do it |
| Need to add a caution? This is how to do it |
| Need to add a warning? This is how to do it |
Use a short section in bold at the start of the admonition to try to attract the readers attention.
If you need a longer admonition you can use a sidebar block:
For more information, see the CircleCI style guide.
Troubleshooting
If there is troubleshooting information for the feature or task, list it here. Use a question and answer format to make it easier to read. If a troubleshooting step applies to an error message, include the error message in the question to help people to find the solution.