Documentation Issue Template

Documentation Issue Template

Documentation issues are fundamentally different from code bugs. A dedicated template helps collect the right information: which page has the problem, what type of issue it is, and what the correct content should be.

Template Structure

name: "Documentation Issue"
description: "Report a docs problem or suggest an improvement"
title: "[Docs]: "
labels: ["documentation"]
body:
  - type: dropdown
    id: issue_type
    attributes:
      label: "Issue Type"
      options:
        - "Incorrect information"
        - "Missing documentation"
        - "Unclear or confusing"
        - "Outdated content"
        - "Broken links or images"
        - "Typos or grammar"
        - "Missing code examples"
    validations:
      required: true
  - type: input
    id: page_url
    attributes:
      label: "Page URL"
      description: "Link to the affected documentation page"
      placeholder: "https://docs.example.com/..."
    validations:
      required: true
  - type: textarea
    id: current_content
    attributes:
      label: "Current Content"
      description: "Quote or describe the problematic content"
    validations:
      required: true
  - type: textarea
    id: suggested_change
    attributes:
      label: "Suggested Change"
      description: "What should the documentation say instead?"
    validations:
      required: false
  - type: input
    id: related_docs
    attributes:
      label: "Related Pages"
      description: "Other documentation pages affected by this issue"
      placeholder: "https://docs.example.com/..."
    validations:
      required: false

Why Separate from Bug Reports?

Documentation issues typically have different assignees, different priority levels, and different resolution workflows. A dedicated template ensures they reach the right people and include context specific to content quality.

The Issue Type Dropdown

Categorizing the issue type upfront helps documentation teams prioritize: incorrect information and broken links need immediate attention, while typos and grammar issues can be batched.

Encouraging Pull Requests

Add a markdown section with a link to the contributing guide, encouraging reporters to submit a PR with the fix. Many documentation issues can be resolved by the reporter themselves.