On This Page
This template will help you create a new docs page that shows the reader how to carry out a task and accomplish a specific goal with CircleCI. Content templates help you to:
To use this template, make a copy and place it in the
Contributors from within CircleCI can also consider setting up a local development environment to preview changes before pushing. Ping one of the Developer Resources and Engineering team (DRE) for more information.
In a how-to guide, include one or two opening paragraphs. The opening paragraph should be used to briefly describe to the reader what the reader will do using this guide, and what the outcomes are when they successfully finish the task. The information in the opening paragraph should help answer the following questions for the reader:
"What’s in it for me?"
"How does this feature / task help me create more value?"
|Since the reader will usually want to quickly get to the task at hand, keep the introduction succinct.|
This is the first subsection in the how-to guide. List any prerequisites that the reader needs to have already met in order for them 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
Roles and permissions
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
Sometimes, there may be topics to know or tasks to complete that are helpful in order to successfully finish the how-to guide, but do not necessarily have a negative impact on the user’s flow if they only do those as they go along. For example, you may include generating an API token in the how-to steps itself, rather than listing it as a strict prerequisite. Use your best judgment to decide whether to add such a requirement as a prerequisite or as a step that is part of the how-to.
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 using the feature.
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. This is a subsection title
Subsections can be used to break steps into logical sub-parts as needed. Level 2 section titles (
===) should also be ordered:
Break up large blocks of text where possible to help make it easier to consume. You can use bullet lists:
2. Using tables
This is the syntax for creating a table. This example has one heading row and one normal row. The table has three columns
|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.
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:
# at the end of the filename. You can place the subsection anchor there if you want to link to a subsection:
4. Code examples
Whenever possible, the how-to guide should provide examples that cover our users' 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:
version: 2.1 jobs: build: docker: - image: cimg/base:2021.04 steps: - checkout - 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^^^'
In technical writing we use admonitions to create blocks of content that stand out from the main flow of text. Outside the docs team we usually refer to these as banners. Currently we have the option to include notes, cautions, and warnings, as follows:
|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|
We try to use a short section in bold at the start of the admonition to try to attract the readers attention.
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.
End the guide with a conclusion section that summarizes what was covered.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.