Documentation Generation

6 minute read

Module Overview

Documentation is critical for provider adoption and usability. This module covers automated documentation generation using tfplugindocs, writing effective documentation, and creating comprehensive guides and examples.

Why Documentation Matters

User Experience

Good documentation enables users to:

  • Understand resource capabilities
  • Find configuration examples
  • Troubleshoot issues quickly
  • Learn best practices

Provider Discovery

Well-documented providers:

  • Appear in Terraform Registry search
  • Get better user reviews
  • Attract more contributors
  • Build community trust

Maintenance Benefits

Comprehensive documentation:

  • Reduces support burden
  • Serves as reference for maintainers
  • Documents design decisions
  • Facilitates onboarding

Documentation Structure

Terraform providers follow a standard documentation structure:

docs/
├── index.md                    # Provider overview
├── data-sources/              # Data source docs
│   ├── cache.md
│   └── caches.md
├── resources/                 # Resource docs
│   ├── cache.md
│   ├── cluster.md
│   └── vpc.md
├── guides/                    # User guides
│   ├── getting-started.md
│   ├── authentication.md
│   └── migration.md
└── functions/                 # Provider-defined functions
    └── encode_id.md

Documentation Generation Tools

tfplugindocs

The official tool for generating provider documentation:

# Install tfplugindocs
go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest

# Generate documentation
tfplugindocs generate

# Validate documentation
tfplugindocs validate

What It Generates

  • Schema documentation: Extracted from resource/data source schemas
  • Import documentation: From ImportState examples
  • Examples: From templates and examples
  • Argument reference: Automatic from schema attributes
  • Attribute reference: Computed attributes documentation

Documentation Components

Provider Documentation

Main provider page with:

  • Overview and purpose
  • Authentication methods
  • Configuration options
  • Quick start example
---
page_title: "CacheCloud Provider"
description: |-
  The CacheCloud provider is used to interact with CacheCloud resources.
---

# CacheCloud Provider

The CacheCloud provider allows Terraform to manage CacheCloud infrastructure.

## Example Usage

```terraform
provider "cachecloud" {
  api_key  = var.cachecloud_api_key
  endpoint = "https://api.cachecloud.example.com"
}

Authentication

The provider supports multiple authentication methods…


### Resource Documentation

Each resource needs:
- Description and use cases
- Example usage
- Argument reference
- Attribute reference
- Import instructions
- Timeouts

### Data Source Documentation

Each data source needs:
- Description and use cases
- Example usage
- Argument reference (filters)
- Attribute reference (outputs)

### Guides

Topic-specific guides:
- Getting started
- Authentication setup
- Common patterns
- Migration guides
- Troubleshooting

## Module Chapters

This module covers documentation generation in depth:

### [Chapter 1: tfplugindocs Tool →](/hashicorp/terraform-provider-development/tfplugindocs-tool/)

Learn to use tfplugindocs for automated documentation generation.

**Topics:**
- Installing tfplugindocs
- Generating documentation
- Documentation validation
- Customization options
- CI/CD integration

### [Chapter 2: Resource Documentation →](/hashicorp/terraform-provider-development/resource-documentation/)

Write comprehensive resource documentation with examples and references.

**Topics:**
- Resource page structure
- Writing descriptions
- Example usage
- Argument reference
- Import documentation
- Timeout configuration

### [Chapter 3: Data Source Documentation →](/hashicorp/terraform-provider-development/data-source-documentation/)

Document data sources with clear usage examples and attribute references.

**Topics:**
- Data source page structure
- Query and filter documentation
- Example usage
- Output attributes
- Multiple results handling

### [Chapter 4: Provider Configuration →](/hashicorp/terraform-provider-development/provider-configuration-docs/)

Document provider configuration, authentication, and setup.

**Topics:**
- Provider overview page
- Authentication documentation
- Configuration options
- Environment variables
- Quick start examples

### [Chapter 5: Guides & Examples →](/hashicorp/terraform-provider-development/guides-examples/)

Create comprehensive guides and real-world examples.

**Topics:**
- Getting started guides
- Authentication guides
- Common use cases
- Best practices guides
- Troubleshooting guides

### [Chapter 6: Documentation Best Practices →](/hashicorp/terraform-provider-development/documentation-best-practices/)

Follow best practices for clear, maintainable documentation.

**Topics:**
- Writing style guidelines
- Example quality
- Versioning documentation
- Screenshots and diagrams
- Accessibility

### [Chapter 7: Documentation Lab →](/hashicorp/terraform-provider-development/documentation-lab/)

Generate and customize documentation for a complete provider.

**Topics:**
- Setting up tfplugindocs
- Writing templates
- Generating docs
- Adding custom guides
- Publishing to registry

## Documentation Quick Reference

### Resource Documentation Template

```markdown
---
page_title: "cachecloud_cache Resource - CacheCloud"
subcategory: ""
description: |-
  Manages a CacheCloud cache instance.
---

# cachecloud_cache (Resource)

Provides a CacheCloud cache resource for managing cache instances.

## Example Usage

```terraform
resource "cachecloud_cache" "example" {
  name      = "my-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
  num_nodes = 1
}

Schema

Required

  • name (String) The name of the cache.
  • engine (String) The cache engine (redis or memcached).

Optional

  • node_type (String) The node type. Defaults to cache.t3.micro.
  • num_nodes (Number) Number of nodes. Defaults to 1.

Read-Only

  • id (String) The cache ID.
  • endpoint (String) The cache endpoint.
  • status (String) The current status.

Import

Caches can be imported using the cache ID:

terraform import cachecloud_cache.example cache-123456


### Data Source Documentation Template

```markdown
---
page_title: "cachecloud_cache Data Source - CacheCloud"
subcategory: ""
description: |-
  Get information about a CacheCloud cache.
---

# cachecloud_cache (Data Source)

Use this data source to get information about an existing cache.

## Example Usage

```terraform
data "cachecloud_cache" "example" {
  name = "my-cache"
}

output "cache_endpoint" {
  value = data.cachecloud_cache.example.endpoint
}

Schema

Optional

  • name (String) The name of the cache.
  • id (String) The ID of the cache.

Read-Only

  • endpoint (String) The cache endpoint.
  • status (String) The current status.
  • engine (String) The cache engine. ```

Automation

CI/CD Integration

# .github/workflows/docs.yml
name: Documentation

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'templates/**'
      - 'examples/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      
      - name: Install tfplugindocs
        run: go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest
      
      - name: Generate docs
        run: tfplugindocs generate
      
      - name: Check for changes
        run: |
          git diff --exit-code || (echo "Documentation is out of date. Run 'tfplugindocs generate'" && exit 1)

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Generate documentation
tfplugindocs generate

# Check if docs changed
if ! git diff --exit-code --quiet docs/; then
    echo "Documentation generated. Please review and commit changes."
    git add docs/
fi

Best Practices

1. Keep Examples Simple

# ✅ Good: Simple, focused example
```terraform
resource "cachecloud_cache" "example" {
  name      = "my-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
}

❌ Bad: Complex, unfocused example

resource "cachecloud_cache" "example" {
  name      = "my-cache-with-backup-and-replication-in-multiple-azs"
  engine    = "redis"
  # ... 20 more attributes
}


### 2. Document All Attributes

```markdown
# ✅ Good: Complete documentation
### Optional

- `port` (Number) The port number (1024-65535). Defaults to `6379`.
- `parameter_group` (String) The parameter group name.

# ❌ Bad: Missing details
### Optional

- `port` (Number) Port
- `parameter_group` (String) Parameter group

3. Provide Real-World Examples

# ✅ Good: Realistic scenario
## Example Usage

### Basic Cache

```terraform
resource "cachecloud_cache" "basic" {
  name      = "session-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
}

Production Cache with Backups

resource "cachecloud_cache" "production" {
  name      = "prod-cache"
  engine    = "redis"
  node_type = "cache.m5.large"
  num_nodes = 3
  
  backup_enabled        = true
  backup_retention_days = 7
}


### 4. Include Import Examples

```markdown
# ✅ Good: Clear import instructions
## Import

Import using the cache ID:

```shell
terraform import cachecloud_cache.example cache-123456

For caches with composite IDs (region/id):

terraform import cachecloud_cache.example us-east-1/cache-123456

```

Documentation Checklist

When documenting your provider:

  • ✅ Run tfplugindocs to generate base documentation
  • ✅ Add provider overview with authentication
  • ✅ Document all resources with examples
  • ✅ Document all data sources with examples
  • ✅ Create getting started guide
  • ✅ Add authentication guide
  • ✅ Include import instructions for resources
  • ✅ Document timeouts if applicable
  • ✅ Add troubleshooting guide
  • ✅ Include real-world examples
  • ✅ Validate documentation with tfplugindocs validate
  • ✅ Test all code examples
  • ✅ Check for broken links
  • ✅ Review for clarity and completeness

What You’ll Learn

By the end of this module, you’ll be able to:

  • ✅ Use tfplugindocs to generate documentation
  • ✅ Write comprehensive resource documentation
  • ✅ Create effective data source documentation
  • ✅ Document provider configuration
  • ✅ Write helpful guides and examples
  • ✅ Follow documentation best practices
  • ✅ Automate documentation generation
  • ✅ Validate documentation quality

Getting Started

Begin with Chapter 1: tfplugindocs Tool to learn how to use the official documentation generation tool.

Start Chapter 1 →

Previous: ← Validation Practice
Next: tfplugindocs Tool →

Last updated: June 30, 2026

Updated:

You may also enjoy