Page title
29 days ago
Include one opening paragraph to briefly describe what the reader will do by following the guide. The information in the opening paragraph should help 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?
| If available, provide a link to an overview or conceptual doc for more explanatory or background information regarding the task. |
Prerequisites
List any prerequisites that the reader needs to have already met in order to successfully complete the task. These may include:
-
Completing a certain task, such as signing up for a CircleCI account and having at least one project building in CircleCI
-
CircleCI plan requirements
-
Roles and permissions
-
Skills/knowledge
-
Link to any helpful documentation or pages that they can refer to, for example, "For more information on how test splitting works, refer to the Test splitting and parallelism page."
-
-
Any other dependencies
1. Carry out the task
The main body of the guide should be broken into logical steps, with headings for each step. The steps should guide the reader through carrying out the task.
Write the section headings with an active voice to show what will be done. The reader should ideally be able to read the page table of contents and understand what they will achieve and how.
In a how-to guide, you might walk the reader through an example scenario. Examples should be based on real-world use cases as much as possible and address business objectives.
1.1 This is a subsection title
Subsections can be used to break steps into logical sub-parts as needed. Level 3 section titles (===) should also be ordered:
-
If the document comprises multiple smaller how-to guide, use numbers in the Level 3 titles. (As an example, see the Manage contexts with config policies guide)
-
Otherwise, consider using lowercase letters. (As an example, see Use the CircleCI CLI to split tests)
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
1.2. 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.
1.3. 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:
1.4. Code examples
Whenever possible, the how-to guide should provide examples that cover most widely used languages and frameworks, unless the guide itself is specific to a particular language, platform, or framework.
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^^^'5. 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.
2. The second step
Each main step in the how-to guide should be under its own level 2 (==) heading, using the numbered list format.
