Skip to main content
HashiCorp documentation on developer.hashicorp.com follows the principles of the Diátaxis method for structured documentation. Every page belongs to one of four content types, each with a distinct purpose and audience need.
Tutorials are hosted in a separate repository. This guide focuses on Explanation, Usage, and Reference content types.

​
Content type overview

Explanation

Conceptual content that helps readers understand a product’s underlying systems, architecture, and workflows. Includes Index, Overview, and Concept pages.

Usage

Step-by-step procedural content that guides readers through completing a specific task.

Reference

Factual, scannable content for configuration options, CLI commands, and API endpoints.

Tutorials

Hands-on learning content hosted in a separate tutorials repository.

​
Explanation pages

Within the Explanation category, three distinct page subtypes serve different purposes.
Index pages provide lists of links to supporting documentation on a subject. They help readers navigate to the specific content they need.Example: Deploy ConsulUse an index page when a subject area has multiple supporting pages and readers benefit from a curated entry point with links rather than a full explanation.
Overview pages provide an introduction to a subject and serve as a central information point. They explain what a feature or system is, why it matters, and link to related usage and reference content.Example: Expand service network east/westUse an overview page when a subject area is broad enough to require orientation before a reader dives into tasks.
Concept pages provide discursive explanations of a product’s underlying systems and their operations. They define terms, explain how components relate, and give readers a mental model.Example: Consul catalogUse a concept page when readers need to understand why or how something works before they can effectively follow procedural guidance.

​
Page templates

Use these templates as a starting point when creating a new page. Adapt the structure to fit your content, but keep the frontmatter fields and section order consistent.
The usage template is for procedural, task-oriented content.
---
page_title: Match the H1 and nav title
description: |-
  Include target keywords and keyword phrases so that users can easily search.
---

# Title

Explain what the topic is about.

## Requirements

The requirements block describes the following information necessary to operate the product:

- system
- environment
- software requirements
- product version: Note that because we have versioned docs, specifying the core product
  version is not as important as version requirements for ancillary software, such as `kubectl`.

## Steps

Depending on the context, you can either add an introduction statement about the procedure
or begin describing the procedure directly.

1. If the procedure describes a series of commands, we recommend setting environment variables
   as the first step so that you can use the variable name in subsequent commands.
   Always link to the relevant [reference documentation](link):

   <COMMAND>
   <RESPONSE>

1. The next step may require the user to configure a file.
   Always link to the relevant [reference documentation](link):

   <CodeBlock>
   </CodeBlock>

1. The final step may require another command:

   <COMMAND>
   <RESPONSE>

## Next steps

Introduce related tasks that either enhance this topic or are necessary to achieve a larger goal.
Next steps link to other usage pages, rather than additional conceptual or reference information.

​
When to use each content type

You want to…Use this content type
Explain what something is or how it worksConcept
Walk readers through completing a taskUsage
Provide an entry point to a subject areaIndex or Overview
Document all options, flags, or parametersReference
Teach through a hands-on exerciseTutorial (separate repo)
HashiCorp employees can refer to the internal Technical Writing wiki for detailed explanations and additional guidance on each content type.

Build docs developers (and LLMs) love

Get started for freeTalk to us