Issue Tracking for Documentation — Complete Guide

Issue tracking manages documentation tasks through creation, assignment, prioritization, and completion. Learn how to track doc issues in project management systems.

What You'll Learn

You will learn how to create good documentation issues, use labels and milestones, prioritize documentation work, and track progress.

Why It Matters

Documentation without issue tracking is invisible. No one knows what needs to be done, who is doing it, or what is blocked.

Real-World Use

DodaTech uses GitHub issues with labels like "tutorial," "reference," "bug," and "good first issue." Each issue includes a checklist of required sections.

flowchart LR
  A[Issue Tracking] --> B[Creation]
  A --> C[Organization]
  A --> D[Workflow]
  B --> E[Template]
  B --> F[Checklist]
  C --> G[Labels]
  C --> H[Milestones]
  D --> I[Assignment]
  D --> J[Status]
  E:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Creating Good Documentation Issues

Issue Template

## Documentation Issue Template

### Topic
[Brief description of the documentation needed]

### Content Type
- [ ] Tutorial
- [ ] Reference
- [ ] How-to Guide
- [ ] Troubleshooting
- [ ] Update existing page

### Priority
[High / Medium / Low]

### Requirements
- [ ] 1200+ words
- [ ] 3+ code examples
- [ ] Common Mistakes section
- [ ] Practice Questions section
- [ ] FAQ section
- [ ] Mini Project

### Related Issues
[Link to related issues]

### Additional Context
[Any relevant information]

Example Issue

def create_doc_issue(topic, content_type, priority):
    issue = {
        'title': f"Write {content_type}: {topic}",
        'labels': [content_type, priority],
        'body': f"""
## Topic
{topic}

## Content Type
{content_type}

## Priority
{priority}

## Checklist
- [ ] First paragraph 140-165 characters
- [ ] Mermaid diagram
- [ ] 3+ code examples
- [ ] 5+ common mistakes
- [ ] 3+ practice questions
- [ ] 5+ FAQ items
- [ ] Mini project
        """,
    }
    return issue

issue = create_doc_issue('Python File Handling', 'tutorial', 'High')
print(f"Title: {issue['title']}")
print(f"Labels: {issue['labels']}")

Expected output:

Title: Write tutorial: Python File Handling
Labels: ['tutorial', 'High']

Labeling Issues

Tracking Progress

Milestones

Group issues into milestones for releases or sprints.

milestone:
  name: "July 2026 Documentation Sprint"
  due_date: 2026-07-31
  issues:
    - "Write Python File Handling tutorial"
    - "Update API authentication guide"
    - "Fix broken links in getting started"

Status Tracking

def track_milestone_progress(issues):
    total = len(issues)
    completed = sum(1 for i in issues if i['status'] == 'completed')
    in_progress = sum(1 for i in issues if i['status'] == 'in_progress')
    planned = sum(1 for i in issues if i['status'] == 'planned')
    
    return {
        'total': total,
        'completed': completed,
        'in_progress': in_progress,
        'planned': planned,
        'completion': (completed / total) * 100 if total > 0 else 0,
    }

issues = [
    {'title': 'Tutorial A', 'status': 'completed'},
    {'title': 'Tutorial B', 'status': 'in_progress'},
    {'title': 'Tutorial C', 'status': 'planned'},
    {'title': 'Tutorial D', 'status': 'planned'},
]
progress = track_milestone_progress(issues)
print(f"Completion: {progress['completion']:.0f}%")

Expected output:

Completion: 25%

Common Mistakes

1. Vague Issues

Issue titled "Improve documentation" with no specifics. Every issue must describe exactly what is needed.

2. No Acceptance Criteria

Without a checklist, contributors do not know when the issue is done. Add a checklist to every issue.

3. Stale Issues

Issues that remain open for months without action should be reviewed and either closed or reprioritized.

4. No Labels

Issues without labels cannot be filtered. Contributors cannot find good first issues.

5. Assigning Without Confirming

Assigning an issue to someone without asking if they want to work on it leads to abandoned issues.

Practice Questions

1. What information should a documentation issue include?

Topic, content type, priority, checklist of requirements, and related issues.

2. Why are labels important for issue tracking?

Labels enable filtering and help contributors find issues they want to work on.

3. What is a milestone in issue tracking?

A group of issues targeted for completion by a specific date, such as a release or sprint.

4. Why include acceptance criteria in every issue?

So contributors know exactly when the issue is done and reviewers know what to check.

5. Challenge: Create 5 documentation issues for a project. Include templates, labels, priorities, and checklists.

FAQ

Mini Project

Set up an issue tracking system for a documentation project. Create an issue template, define 8 labels, create a milestone with 5 issues, and define the workflow from creation to completion.

What's Next

Now that you understand issue tracking, learn Pull Request Templates. Then study Review Process for Docs.