Documentation Best Practices

This skill provides guidance for creating consistent, professional documentation for the MTG Agent project implementation.

Purpose

Maintain high-quality, actionable documentation that follows senior developer standards with:

Clear task breakdowns with time estimates
Comprehensive verification steps
Rollback procedures for safety
Testing integrated throughout
Professional commit messages

When to Use This Skill

Use this skill when:

Creating new phase documentation
Writing task breakdowns for implementation
Documenting verification procedures
Setting up testing requirements
Creating progress tracking documents
Writing commit messages
Updating implementation plans

Documentation Structure Standards

Phase README Format

Each phase README should include:

Phase Overview

- Phase number and name - Status (Not Started, In Progress, Completed) - Duration estimate - Prerequisites

Objectives

- Clear, measurable goals - 3-5 bullet points max - Specific deliverables

Why This Phase

- Business/technical justification - Dependencies explained - Risk mitigation

Sub-Phases

- List of sub-phases with brief descriptions - Estimated time for each - Dependencies between sub-phases

Success Criteria

- Checklist of completion requirements - Verification that phase is truly done - Performance targets if applicable

Next Phase

- Link to next phase - What will be built upon

Task Documentation Format

Each task should include:

Task Header

``markdown ### Task X.Y: [Clear Task Name] Estimated Time: X minutes/hours Prerequisites: [What must be done first] ``

Objectives

- What this task accomplishes - Why it's necessary

Steps

- Numbered, specific steps - Include commands to run - Code examples where applicable - File paths clearly stated

Verification

``markdown Verification: `bash # Commands to verify task completion command1 command2 ``

Expected Output: - What success looks like ```

Success Criteria

``markdown - [ ] Specific criterion 1 - [ ] Specific criterion 2 - [ ] Specific criterion 3 ``

Common Issues

- Known problems and solutions - Troubleshooting steps

Code Examples

To include code examples:

For Configuration Files: ```markdown Create: path/to/file.ext`

// Full file content here
// With comments explaining key parts

````

For Commands: ````markdown

# Comment explaining what this does
command --flag value

````

For Multi-Step Procedures: ````markdown

# Step 1: Setup
command1

# Step 2: Execute
command2

# Step 3: Verify
command3

````

Verification Steps Format

Every task must include verification:

**Verification:**

Test command 1

curl http://localhost:3000/health

Test command 2

npm test

Test command 3

docker-compose ps


**Expected Output:**
- Service returns 200 OK
- All tests pass
- All containers running

**Success Criteria:**
- [ ] Command 1 passes
- [ ] Command 2 passes
- [ ] Command 3 passes

Rollback Procedures

Include rollback steps for safety:

## Rollback Procedure

If this task causes issues:

Step 1: Stop services

docker-compose down

Step 2: Restore from backup

git checkout <previous-commit>

Step 3: Restart

docker-compose up -d


**When to Rollback:**
- Verification fails repeatedly
- Breaks existing functionality
- Introduces security vulnerability

Commit Message Standards

Follow conventional commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style (formatting, no logic change)
refactor: Code refactoring
test: Adding tests
chore: Build process, dependencies

Examples:

feat(auth): add session-based authentication middleware

Implement session-based authentication with bcrypt password hashing.
Includes middleware for protected routes and session validation.

- Add bcrypt password hashing
- Create session middleware with Redis store
- Implement auth middleware
- Add tests for auth flow

Closes #123

fix(rate-limit): correct Redis connection leak

Fixed issue where Redis connections weren't properly closed,
causing connection pool exhaustion under load.

- Close Redis connections in finally block
- Add connection pool monitoring
- Update tests to verify cleanup

docs(phase1): add database setup documentation

Created comprehensive documentation for Phase 1.1 database setup
including schema, migrations, and verification steps.

Progress Tracking

Task Status

Use clear status indicators:

⏸️ Not Started
🔄 In Progress
✅ Completed
❌ Blocked
⚠️ Needs Review

Update Frequency

Update documentation:

✅ Before starting a task (mark in progress)
✅ Immediately after completing task (mark complete)
✅ When blocked (document blocker)
✅ When requirements change

Completion Checklist

Mark tasks complete only when:

Testing Integration

Test Documentation Standard

For each phase/task, document:

## Testing Requirements

### Unit Tests
- [ ] Test X functionality
- [ ] Test Y edge case
- [ ] Test Z error handling

### Integration Tests
- [ ] Test A to B integration
- [ ] Test error scenarios
- [ ] Test performance

### Manual Verification

Command to verify manually

test-command


**Expected Behavior:**
- Specific outcome 1
- Specific outcome 2

Test-First Approach

When possible:

Write verification steps BEFORE implementation
Run verification (should fail initially)
Implement feature
Run verification (should pass)
Document results

Documentation Maintenance

Keep Documentation Current

Update docs in same commit as code changes
Document decisions and rationale
Note workarounds and TODOs
Link related documents

Review and Refactor

Periodically review documentation for:

Outdated information
Broken links
Unclear instructions
Missing verification steps

Templates Usage

To use the bundled templates:

Task Documentation: See references/task-template.md
Verification Steps: See references/verification-template.md
Phase README: See assets/phase-readme-template.md

Load these references as needed when creating new documentation.

Best Practices Summary

✅ DO:

Write clear, specific steps
Include time estimates
Provide verification commands
Document expected outputs
Include rollback procedures
Write tests alongside code
Update docs with code changes
Use consistent formatting

❌ DON'T:

Leave verification steps vague
Skip rollback procedures
Document without testing
Mix multiple concerns in one task
Forget to update status
Omit time estimates
Skip commit message body

Examples

See bundled references for complete examples of:

Task documentation with full verification
Phase README with comprehensive breakdown
Verification step templates

documentation-best-practices

Installation

Similar popular skills

Also in this package

Agent compatibility

Package contents

History

SKILL.md

Documentation Best Practices

Purpose

When to Use This Skill

Documentation Structure Standards

Phase README Format

Task Documentation Format

Code Examples

Verification Steps Format

Test command 1

Test command 2

Test command 3

Rollback Procedures

Step 1: Stop services

Step 2: Restore from backup

Step 3: Restart

Commit Message Standards

Progress Tracking

Task Status

Update Frequency

Completion Checklist

Testing Integration

Test Documentation Standard

Command to verify manually

Test-First Approach

Documentation Maintenance

Keep Documentation Current

Review and Refactor

Templates Usage

Best Practices Summary

Examples