Skip to content

Workflow Documentation Template

This template defines the standard structure for workflow documentation pages. Use this when creating or enhancing workflow documentation to ensure consistency and practitioner-friendliness.

Required Sections

These sections MUST be included in every workflow documentation page.

1. Prerequisites

Purpose: Help practitioners verify they have everything needed before starting.

Format: 

## Prerequisites

Before starting, ensure you have:

- Claude Code or OpenCode installed ([Quickstart](../get-started/quickstart.md))
- [Specific tool/access needed]
- [Optional: Additional requirements]

!!! tip "Stuck?"
    Running into issues? Check the [Troubleshooting Guide](../help/troubleshooting.md).

Example: See First Content Audit

2. What You Get

Purpose: Set clear expectations about deliverables and outcomes.

Format: 

**What you get:**

- [Deliverable 1 with brief description]
- [Deliverable 2 with brief description]
- [Deliverable 3 with brief description]

**Time:** [X-Y minutes] (vs. [manual time] manual)

Example: See workflow pages like SEO Workflows

3. How to Run

Purpose: Provide step-by-step instructions for executing the workflow.

Format: 

## How to Run

=== "Claude Code"

    ```bash
    /[plugin]:[command]
    ```

=== "OpenCode"

    ```bash
    /[command]
    ```

The agent will guide you through [X] intake questions:

1. **[Question 1]**: [What to provide]
2. **[Question 2]**: [What to provide]

Example: See First Content Audit

4. Troubleshooting Hook

Purpose: Link to common issues and solutions.

Format: 

## Troubleshooting

Common issues:

1. **"[Error message]"** → See [Troubleshooting Guide](../help/troubleshooting.md#anchor)
2. **"[Error message]"** → See [Troubleshooting Guide](../help/troubleshooting.md#anchor)
3. **"[Error message]"** → See [Troubleshooting Guide](../help/troubleshooting.md#anchor)

Optional Sections

These sections enhance documentation but are not required.

5. Time Estimate

Purpose: Help practitioners plan their work.

Format: 

!!! tip "Time Required"
    - **Setup**: [X] minutes
    - **Execution**: [X-Y] minutes
    - **Review**: [X-Y] minutes

Purpose: Guide practitioners to complementary workflows.

Format: 

## Related Workflows

- [Workflow Name](link.md) - [When to use it]
- [Workflow Name](link.md) - [When to use it]

7. Example Prompts

Purpose: Provide copy-paste examples for common scenarios.

Format: 

## Example Scenarios

### Scenario 1: [Use Case]

**When to use**: [Description]

**Example prompt**:
\`\`\`
[Copy-paste example]
\`\`\`

Best Practices

  1. Keep it scannable: Use headings, lists, and callouts
  2. Be specific: Provide exact commands and examples
  3. Link generously: Connect to troubleshooting, related workflows, and reference docs
  4. Test your instructions: Have someone unfamiliar with the workflow follow them
  5. Update regularly: Keep time estimates and examples current

Reference Example

The gold standard for this format is First Content Audit.