Instruction file imported from IanMadd/docs-skills (
.github/instructions/doc-types.instructions.md). Copyright stays with the author.
Doc type structures
Source guidance: The Good Docs Project
Tutorial
Purpose: Learning-oriented. The reader follows a guided path and ends with a working result and new skills. Assumes no prior practical knowledge of the tool. Tutorials eliminate unexpected scenarios---engineer the reader toward a successful finish.
Tutorials differ from how-to guides: tutorials teach; how-to guides guide experienced users through a task.
# <Title: what the reader will build or achieve>
One paragraph explaining what the reader will build and why it matters to a DevOps engineer.
## Overview
### Learning objectives
By the end of this tutorial, you'll be able to:
- <Skill or action the reader can perform>
- <Skill or action the reader can perform>
### Intended audience
Who this tutorial is for and what prior knowledge is assumed.
## Background (optional)
Any context the reader needs before starting---feature explanation, project structure, key concepts.
Keep this brief; link to conceptual docs for deeper explanations.
## Before you begin
- Prerequisite 1 (link to setup steps where applicable)
- Prerequisite 2
## Step 1: <Bare infinitive action---"Configure the namespace">
Introductory sentence explaining what this step accomplishes and why.
1. Step action. Start with an imperative verb.
1. Step action.
```shell
# Comment explaining what this command does
command --flag <value>Expected result: describe what the reader should see.
Step 2:
...
Summary
Recap the specific skills and knowledge the reader gained. Don't repeat the learning objectives word-for-word---describe what they actually built or configured.
Clean up (include if tutorial creates persistent or billable resources)
Steps to remove resources created during the tutorial.
Next steps
- Link to a related how-to guide
- Link to a related conceptual doc or advanced tutorial
**Guidelines**:
- Tutorials should take 15–60 minutes to complete
- Keep steps to a maximum of 7 primary steps; maximum 4 substeps per step
- Each step builds on the previous one---don't jump ahead
- Show expected output after commands so the reader can verify success
- Use real, working examples---not placeholder logic
- Add comments to all code samples explaining what each part does
- Include a "Clean up" section whenever the tutorial creates persistent or billable resources
---
## How-to guide
**Purpose**: Task-oriented. Helps an experienced reader complete one specific task or solve one specific problem. Assumes the reader has practical knowledge and knows what they want to achieve. Alerts readers to unexpected scenarios; it doesn't eliminate them the way a tutorial does.
```markdown
# <Title: bare infinitive---"Deploy a container to Kubernetes">
One or two sentences describing the task and when a reader would perform it.
For example: "Use this guide to create a Kubernetes NetworkPolicy that restricts pod-to-pod traffic."
If it's not obvious why the reader should do this task, state the benefit or outcome.
If the task is routine (for example, a recurring backup) or follows another event (for example, an
upgrade), state when to perform it.
If the task carries risk or requires a safety measure first---a backup, a maintenance window, elevated
permissions---state it before the steps.
If the task takes a long time or affects a critical system, tell the reader up front.
## Before you begin (include only for non-obvious prerequisites)
- Prerequisite: tool, permission, or environment needed
- Link to relevant setup docs
- If the reader will install third-party software, link to that software's system requirements
## <Task name: bare infinitive>
(Include an introductory sentence unless the heading alone gives the reader everything they need.)
Introductory sentence that adds context the heading doesn't already cover---don't just repeat the
heading. End the sentence with a colon if it immediately precedes the steps, or a period if other
material (for example, a note) comes between the sentence and the steps.
For example: "To customize the buttons, follow these steps:" or "Customize the buttons:"
Don't introduce the steps with a partial sentence that the numbered list completes, for example,
"To customize the buttons:" followed directly by the steps.
1. Step one. Start with an imperative verb. Write each step as one action or one decision the reader
makes---write at the highest level the reader will understand rather than splitting one action into
several small steps.
1. Step two.
```shell
# Comment explaining the command
command --flag <value>
Replace <value> with .
Expected output or result.
Explain the significance of the output in a separate paragraph if it isn't obvious.
- Optional: <step that isn't required>.
- If , do .
Next steps
- Link to another procedure the reader should complete after this one
See also
- Link to a related how-to guide
- Link to a relevant conceptual doc or reference page
**Guidelines**:
- One how-to guide covers exactly one task
- Maximum 8–10 steps; if longer, split into multiple guides, or group related steps under subheadings so
the reader stays oriented
- Introduce a set of steps with a sentence that adds context beyond the heading; skip the introductory
sentence entirely if the heading already says everything the reader needs
- End an introductory sentence with a colon when the steps follow immediately, or a period when other
material comes between the sentence and the steps
- Write the introductory sentence as a complete imperative statement, not a partial sentence the
numbered steps complete---write "To customize the buttons, follow these steps:" or
"Customize the buttons:", not "To customize the buttons:"
- Apply the same introductory-sentence rules to a step that has sub-steps: end that step with a colon
or a period, as appropriate, before listing the sub-steps
- Write each step as a single action the reader takes or a single decision they make; if an action
triggers a response from the application or system, describe that response in the same step, not as
its own step
- Start the first sentence of every step with an imperative verb
- Preface optional steps with "Optional:"
- State conditions at the start of a step, not the end, so the reader doesn't act before realizing the
condition doesn't apply to them---for example, "If the test succeeds, reindex all organizations," not
"Reindex all organizations if the test succeeds"
- Use a single unordered list item, not a numbered step, for single-step procedures
- Don't explain concepts in the steps---link to conceptual docs instead
- Document only the most common or recommended method; omit or link to alternative methods
- Alert readers to possible unexpected scenarios with `> **Note:**` or `> **Warning:**` admonitions
- Make the end point of the procedure clear---show expected output, a verification command, or a
screenshot so the reader knows they reached the end point, whether it's the end of the guide or a
waypoint in a longer set of procedures
- Test instructions end-to-end before publishing; re-test after every notable product release
- Include "Next steps" when the how-to guide is part of a larger workflow and leads directly into other procedures; omit it for standalone tasks
---
## Reference doc
**Purpose**: Provides accurate, complete technical information designed to be scanned, not read top to bottom. Mirrors the structure of the application or system it documents. Avoid high-level instructions or usage guides---link to how-to guides instead.
```markdown
# <Title: noun phrase---"kubectl rollout options">
One sentence describing what this reference covers.
## Syntax
`command [flags] <arguments>`
## Description
What the command, option set, or configuration does. Keep this concise.
## Options
`--flag`
: What it does.
Type: string
Default: `""`
`--required-flag`
: What it does.
Type: int
Default: required
## Examples
```shell
# Description of what this example does
command --flag <value>
# Description of a second variation
command --flag <value> --other-flagRelated
- Link to related reference page
- Link to related how-to guide
**Guidelines**:
- Every flag, option, and parameter must be documented; include type and default
- Document each flag or option as a description list: the term is the flag in code font, and the
definition starts with a one-line description followed by indented `Type:` and `Default:` lines
- Use `required` for the `Default:` value when there is no default value
- Examples must be present---at least two, showing different configurations
- Use active voice in descriptions: "Returns a JSON object" not "A JSON object is returned"
- Use description lists and bulleted lists to maximize scannability
- Maintain consistent structure, terminology, and tone across all reference pages
- Don't include step-by-step procedures---link out to how-to guides
---
## Conceptual doc
**Purpose**: Helps readers understand a concept, architecture, or system. Provides foundational knowledge so readers can understand how-to guides and reference docs in context. Builds mental models; does not teach by doing.
Conceptual docs appear early in documentation journeys, or as mid-level layers when a reader encounters an unfamiliar concept in a how-to guide.
```markdown
# <Title: noun phrase---"Deployment strategies in Kubernetes">
(Optional) An introductory paragraph framing the concept's relevance and what the page covers.
Apply the inverted pyramid: start with the high-level idea, then go deeper.
## What is <concept>
A clear definition scoped to what this document covers. State what is in scope and, where useful,
what is out of scope. Explain how the concept fits into the broader system or workflow.
Use analogies where they help---prefer universally understood comparisons.
## (Optional) <Diagram or visual>
If a diagram clarifies the architecture or data flow, describe or embed it here, near the top.
## (Optional) Background
Historical context, design decisions, or industry context that affects how the concept works.
Include only if it meaningfully aids understanding.
## Use cases
When and why a DevOps engineer would use or encounter this concept.
Frame use cases around the reader's problems: what challenges does this concept solve?
## (Optional) Comparison
If the concept has multiple types, versions, or similar alternatives, include a comparison table.
| | When to use |
|---|-------------|
| <Option 1> | <Reason> |
| <Option 2> | <Reason> |
## Related resources
- Link to related conceptual doc
- Link to how-to guide that implements this concept
- Link to reference doc for this concept's options or configuration
Guidelines:
- One conceptual doc covers exactly one concept; if explaining a second concept becomes necessary, link to a separate doc
- Don't include step-by-step procedures---add a
<!-- TODO: link to how-to guide for [task] -->comment where a procedure link should go - Use the inverted pyramid: high-level overview first, details later
- Include a diagram whenever it clarifies structure, data flow, or relationships
- Explain trade-offs and limitations honestly
Release notes
Purpose: Communicate new features, improvements, bug fixes, and known issues to stakeholders. Release notes are customer-facing---use plain language, not developer-facing changelog language. Written for both technical and non-technical readers.
## <PRODUCT> <VERSION>
Release date: <MONTH> <DAY>, <YEAR>
(Optional) One to two sentences highlighting the most important items in this release.
### Breaking changes (include if present---always lead with this section)
> **Warning:** The following changes require action before upgrading.
- **<Change name>**: What changed, what the reader must do, and a link to the migration guide.
### New features
- **<Feature name>**: What the feature does and how it benefits the reader.
See [<feature docs>](<link>) for more information.
### New features requiring configuration updates
- **<Feature name>**: What the feature does. To use this feature, you must <describe the required config>.
See [<feature docs>](<link>) for configuration steps.
### Improvements
- **<Area or feature>**: What was added, updated, or removed and the benefit to the reader.
### Bug fixes
- **[<issue-id>](<link>) <Short description>**: The <application or feature> now correctly <does XYZ>. Previously, it <did ABC>.
See [<docs link>](<link>) for more information.
### Known issues
- **[<issue-id>](<link>) <Short description>**: <What happens and in what scenario>.
Workaround: <Steps to work around the issue, if available>.
### Deprecated features (optional)
- **<Feature name>**: <Feature> will be removed in <version or date>.
<Replacement feature> replaces it. The system will <describe data migration if applicable>.
See [<deprecated feature docs>](<link>).
### Packages
Packages are available for the following platforms and architectures:
| Platform | Architecture | Package format |
|----------|--------------|----------------|
| Windows | x86-64 | `.msi` |
| macOS | x86-64, ARM64 | `.pkg` |
| Red Hat Enterprise Linux, CentOS | x86-64, ARM64 | `.rpm` |
| Debian, Ubuntu | x86-64, ARM64 | `.deb` |
| Chef Habitat | x86-64, ARM64 | `.hart` |Guidelines:
- Write in a positive, friendly tone; use plain language
- Use second person: "You can now...", "Use the new... to..."
- Use present tense for new features and improvements: "Adds support for...", "Lets you..."
- For bug fixes, use this two-part pattern: "The now correctly . Previously, it ."
- Don't start bug fix entries with "Fixed..." or "Resolved..."
- List the most important items in each section first
- Include issue or PR numbers and link them where your organization permits
- Omit any section that has no entries
- Use semantic versioning for release numbers (for example,
1.3.2); include the date inYYYY-MM-DDformat - In the Packages section, list only the platforms and architectures available for the specific release; omit rows that don't apply
Product overview
Purpose: Provides a high-level description of a product's value, capabilities, and use cases. This is often the entry point for developers, managers, and executives evaluating a product. Helps readers understand what the product does, why they might use it, and where to find additional resources.
Product overview pages combine information that overlaps with marketing and READMEs, but focus on linking readers to relevant documentation resources within your product ecosystem.
PRODUCT NAME Overview
Introductory paragraph(s) explaining what the product is, what it does, what problems it solves, and the benefits to the user. This content will overlap with marketing for this product. For example, see the AWS Lambda marketing page and the AWS Lambda documentation page.
Product diagram
Include a basic diagram showing how the product works and how components connect at a high level. Reference the Google guide to documentation illustrations for design guidance. See Azure Analysis Services and Azure Cognitive Search for diagram examples.
When to use PRODUCT NAME
Describe the use cases for this product, with one use case per major benefit. Reference Jira's list of use cases as an example. See Azure Cognitive Search use cases for additional guidance.
(Optional) Intended audience and prerequisites
Identify who this product is for, what technical level is assumed, and any prerequisites or background knowledge readers need. Include links to preparatory documentation if readers need to learn concepts before using this product.
(Optional) Key differentiators
Highlight the unique capabilities or features that distinguish this product in the market and address specific user pain points. Focus on what makes this product a good fit for its intended audience.
(Optional) Technical requirements and limitations
List system requirements (OS, memory, storage), geo-availability, licensing constraints, and knowledge prerequisites. Document what this product does NOT do or scenarios it doesn't support to prevent users from discovering limitations after committing to the product.
(Optional) Development effort and scope
Provide realistic guidance on implementation complexity and time investment required. Avoid using words like "easy" or "simple." Instead, qualify effort by audience type and experience level. For example: "For seasoned engineers familiar with X, implementation typically requires one week. For new users unfamiliar with X, allow several months for learning and integration."
PRODUCT NAME components
Component name
Include an H3 heading for each main component or feature. Provide one or more paragraphs summarizing what the component is, what it does, and how it relates to the overall product. Include links in the text to documentation for each component.
Another component
Repeat the pattern above for each component.
Install PRODUCT NAME
Add a link to installation documentation and any relevant system requirements.
Next steps
Provide a brief paragraph or a few sentences guiding readers to the next steps for using this product. Include links to getting started tutorials and documentation for downloading, installing, and configuring the product.
Additional resources
Downloads
- Chef Downloads page for the product
Learning
- Chef webinars for the product
- Learn Chef tutorials for the product
Support
- Chef Help Center for the product
Community
- Section on Chef Discourse for the product
- Section in the Chef Blog for the product
GitHub repositories
Include links to repositories that advanced users might want to explore. This could include the main product repository, resource repositories, or on-premises repositories.
**Guidelines**:
- The product overview page is often the only documentation page that executives will see---prioritize clarity for all audience levels
- Lead with the market problem or pain point the product solves before describing features or benefits
- Include a product diagram whenever possible to show how components connect
- Make use cases concrete and specific; avoid abstract descriptions like "improves collaboration" or "increases efficiency"
- Good example: "X product allows writers to simultaneously edit the same document in a browser without installing software"
- Weak example: "X product helps teams work together more effectively"
- Each use case should map to a distinct product benefit; avoid overly long use case lists
- Link component sections directly to their detailed documentation pages
- Keep introductory paragraphs to one or two paragraphs; avoid dense walls of text
- Follow the file path convention: use `_index.md` in the product subdirectory (for example, `content/habitat/_index.md`)
- Use TOML front matter format and include the `swiftype_search_products` cascade to enable search
- Don't duplicate information that lives in linked documentation---link instead
- Keep the page scannable with clear headings and bulleted lists for resources
- Include only public repositories; exclude private repositories from the GitHub repositories section
- Omit the GitHub repositories section if no public repositories are accessible
- Avoid marketing language like "easy," "simple," or "just"; instead qualify implementation effort by audience type and experience level
- Be honest about implementation complexity; what is straightforward for one audience may be challenging for another
- If marketing content already exists for this product, link to it rather than duplicating; alternatively, create a more technical version focused on implementation
- Optional sections (Intended audience, Key differentiators, Technical requirements, Development effort, Most popular topics) can be excluded if not relevant to your product
- Don't include step-by-step procedures in the overview---link to getting started tutorials or how-to guides instead
---
## README
**Purpose**: The first document a reader finds in a repository.
Answers: what is this, who is it for, why should I care, and how do I start?
Focus on why a reader would engage with the project, not just what it does.
```markdown
# <Project name>
One sentence describing what the project does and who it's for.
<!-- Optional: status badges for build, coverage, version, and license -->
## Project description
Expand on what the project does and why a reader should use it.
Use these patterns:
- "With <project>, you can <verb> <noun>..."
- "<Project> helps you <verb> <noun>..."
- "Unlike <alternative>, <project> <verb> <noun>..."
Include a screenshot or short video clip if it helps readers evaluate the project quickly.
If similar alternatives exist, list what makes this project different.
## Who is this for
Who can use this project, what problems it helps them solve, and what tasks it helps them accomplish.
## Prerequisites
List what the reader needs before they can use the project, and why each is needed.
Link to installation instructions for each.
- <Tool or library> <minimum version>: <Why it's needed>---[Install](<link>)
## Quick start
The minimum steps to get something working. Keep to five steps or fewer.
1. Step one.
1. Step two.
## Installation
```shell
# Install command
<command>
If there are platform-specific steps or multiple installation methods, use a subheading for each.
Configuration
| Variable / Option | Default | Description |
|---|---|---|
VAR_NAME |
"" |
What it controls |
Usage
# Description of what this does
command --flag <value>Show expected output when it helps readers verify success. Link to more complete examples if they're too long to include here.
Troubleshooting
| Problem | Solution |
|---|---|
Contributing
Brief inline guide or link to CONTRIBUTING.md.
State whether you're open to contributions and what you require.
Include any commands needed to run tests or lint the code.
How to get help
Where to ask questions, report bugs, or get support. For example: link to issues, a Slack channel, a mailing list, or Stack Overflow.
Roadmap (optional)
Planned improvements or future release ideas. Use a bulleted list or link to a project board.
Authors and acknowledgment (optional)
Recognize contributors and any third-party libraries or resources used in the project.
Additional documentation (optional)
For large or complex projects, keep the README short and link to separate files.
Common breakouts: CONTRIBUTING.md, INSTALL.md, CHANGELOG.md, SECURITY.md, docs/configuration.md.
License
License name and a link or brief statement.
Project status (include if development has slowed or stopped)
Note if the project is no longer actively maintained, so others can decide whether to fork it or step in as maintainer.
**Guidelines**:
- Choose a self-explaining name for the project
- Lead with why, not just what---explain why a reader should care before describing technical details
- Include status badges near the top to signal project health at a glance; use [Shields.io](https://shields.io/) or your CI provider
- Include a screenshot or short video in the project description when it helps readers evaluate the project quickly
- List differentiating factors if similar alternatives exist
- Keep the README scannable: short paragraphs, code blocks for all commands, clear headings
- Put the quick start before the full installation steps so readers can evaluate the project before committing
- Show expected output after commands so readers can verify their results
- For contributing, document any commands needed to run tests or lint the code; make environment setup steps explicit for both external contributors and your future self
- Include a troubleshooting section for the most common errors new users encounter
- Don't duplicate information that lives in linked docs---link instead
- Split large READMEs into supplementary files and keep the main README as a short entry point with clear links
- Add a table of contents for READMEs with many sections so readers can scan and navigate quickly
- Revisit the README regularly as the project evolves
- If the project is no longer actively maintained, say so prominently at the top of the README