Guide to Writing Machine-Actionable and Human-Readable Documentation

Generated: 2025-01-12 UTC
Purpose: Master the art of dual-purpose documentation that Claude CLI can execute and humans can understand
Audience: Documentation writers, developers, and anyone creating operational guides

---

Core Philosophy: Dual-Purpose Design

Every piece of documentation should serve two audiences simultaneously:

Human Readers Need:

• Visual scanning - Quick identification of sections
• Progressive disclosure - Overview → Details
• Context clues - Understanding without reading everything
• Visual hierarchy - Important things stand out

Claude CLI Needs:

• Explicit context - Purpose, location, prerequisites
• Decision logic - Clear conditions and actions
• Validation steps - Pre-checks before execution
• Parse patterns - Expected outputs and error formats

The Magic: One Document, Two Channels

## 🚀 Deploy Service            <!-- Human: Visual icon catches eye -->
                                <!-- Claude: Section identifier -->

**When to use**: User asks to "deploy", "launch", or "create"  <!-- Claude: Trigger words -->
**When NOT to use**: Service already exists                    <!-- Claude: Exclusion logic -->

```bash
./deploy.sh SERVICE_NAME        # Human: See the command
# Expected output:               # Claude: Parse for success
# ✓ Service created: srv_123

---

## 📋 Essential Components of Machine-Actionable Guides

### 1. CLAUDE-CONTEXT Block (Hidden Metadata)

**Purpose**: Provide machine-readable context without cluttering human view

```markdown
<!-- CLAUDE-CONTEXT
Purpose: What this guide helps accomplish
Location: Working directory or key paths
Prerequisites: Required files, credentials, or state
Safety: Critical warnings about impacts
Key files: Important file relationships
Dependencies: External requirements
-->

Real Example (from Sliplane guide):

<!-- CLAUDE-CONTEXT
Purpose: Manage Sasha deployments on Sliplane via API
Location: /sasha/client-management/
Prerequisites: .env file with credentials, valid client config
Safety: Volumes are SHARED across clients, use dry-run first
Key files: 
  - client-management/.env (credentials)
  - client-management/clients/{NAME}/config.json (required per client)
  - client-management/scripts/*.sh (executable tools)
-->

2. Decision Matrix for Automated Choice

Purpose: Enable Claude to choose the right action based on user intent

## 🤖 Decision Matrix

When user requests [OPERATION]:

### 📋 Decision Tree

User wants to [ACTION]
├── Condition A
│ ├── Check: [validation]
│ ├── Action: [command]
│ └── Verify: [confirmation]
├── Condition B
│ ├── Check: [different validation]
│ └── Action: [different command]
└── Fallback
└── Action: [safe default]

3. Pre-execution Validation Checklist

Purpose: Ensure all prerequisites are met before operations

## ✅ Pre-execution Checklist

**ALWAYS run these checks before any operation:**

```bash
# 1. Verify location
pwd  # Must be in /expected/directory
# If not: cd /expected/directory

# 2. Check required files
[ -f config.json ] && echo "✓ Config exists" || echo "✗ Missing config"

# 3. Validate JSON/YAML
jq '.' config.json >/dev/null 2>&1 && echo "✓ Valid JSON"

# 4. Test connectivity
./test-connection.sh  # Should return success

### 4. Command Blocks with Full Context

**Purpose**: Provide complete execution context for both audiences

```markdown
### 🚀 [Operation Name]

**When to use**: [Specific triggers or conditions]  
**When NOT to use**: [Exclusion conditions]  
**Prerequisites**: [Required state or files]

```bash
# Always start with dry-run
./script.sh --dry-run

# Expected dry-run output:
# "✓ Would create resource X"
# "✓ No conflicts detected"

# If successful, execute:
./script.sh

# Expected success output:
# "✓ Resource created: resource_id_123"
# "✓ Operation completed in 2.3s"

# Verify success:
./verify.sh resource_id_123

Common errors and fixes:

• "Error: Missing config" → Create config.json first
• "Error: Permission denied" → Run chmod +x script.sh
• "Error: Already exists" → Use update command instead

### 5. State Detection Patterns

**Purpose**: Enable Claude to understand current system state

```markdown
## 🔍 State Detection

### Check if Resource Exists
```bash
# Method 1: Direct check with exit code
./check-status.sh RESOURCE_NAME
# Exit code 0 = exists, non-zero = not found

# Method 2: Parse output for confirmation
./check-status.sh RESOURCE_NAME 2>/dev/null | grep -q "Status: active" && \
  echo "Resource is active" || echo "Resource not active"

# Method 3: Extract specific values
STATUS=$(./check-status.sh RESOURCE_NAME | grep "Status:" | awk '{print $2}')
[ "$STATUS" = "active" ] && echo "Ready" || echo "Not ready"

### 6. Error Recovery Patterns

**Purpose**: Provide clear recovery paths for common failures

```markdown
## 🚨 Error Recovery

### [Common Error Scenario]

```bash
# Step 1: Diagnose
./diagnose.sh --verbose
# Look for: "ERROR: specific issue"

# Step 2: Fix based on error type
case "$ERROR_TYPE" in
  "connection")
    ./reset-connection.sh
    ;;
  "permission")
    chmod +x scripts/*.sh
    ;;
  "state")
    ./cleanup.sh && ./reinitialize.sh
    ;;
esac

# Step 3: Retry operation
./original-command.sh

# Step 4: If still failing
./safe-mode-recovery.sh

### 7. Critical Warnings Section

**Purpose**: Establish hard boundaries for safety

```markdown
## ⚠️ CRITICAL WARNINGS - Never Do These

1. **NEVER** delete production data without backup confirmation
2. **NEVER** skip dry-run on first execution of destructive operations
3. **NEVER** modify credentials during active operations
4. **NEVER** assume default values for critical parameters
5. **NEVER** proceed if pre-execution checks fail

---

Formatting Standards

Visual Hierarchy for Humans

Element	Format	Purpose
Main Sections	## 🎯 Section Name	Easy visual scanning
Subsections	### 📋 Subsection	Clear hierarchy
Warnings	⚠️ WARNING: or 🚨 CRITICAL:	Immediate attention
Success	✅ or ✓	Positive confirmation
Failure	❌ or ✗	Error indication
Information	💡 TIP: or 📝 NOTE:	Additional context

Code Block Standards

```bash
# Always include:
# 1. Comment explaining purpose
# 2. The actual command
# 3. Expected output format
# 4. Success indicators

command --with-options

# Expected output:
# Success: specific success message
# Failure: specific error format

### Variable Conventions

- **Placeholders**: Use `{VARIABLE_NAME}` for user-supplied values
- **Environment**: Use `$ENV_VAR` for environment variables
- **Examples**: Provide real examples alongside placeholders

```markdown
Deploy service {SERVICE_NAME}
Example: Deploy service "auth-api"

Path: /home/{USER}/projects
Example: /home/nodejs/projects

---

Complete Guide Template

# [Icon] [Guide Title]

<!-- CLAUDE-CONTEXT
Purpose: [What this guide accomplishes]
Location: [Working directory/context]
Prerequisites: [Required files/state]
Safety: [Critical warnings]
Key files: [Important file list]
-->

**Generated**: YYYY-MM-DD UTC  
**Purpose**: [Human-readable purpose]  
**Audience**: [Target users]

---

## 🤖 Decision Matrix

When user wants to [ACTION]:

### 📋 Decision Tree

[Decision tree structure]

---

## ✅ Pre-execution Checklist

```bash
# Validation commands

---

Operations Reference

[Operation 1]

When to use: [Conditions]
When NOT to use: [Exclusions]
Prerequisites: [Requirements]

# Commands with context

Common errors:

• [Error] → [Solution]

---

State Detection

# State checking commands

---

Error Recovery

[Error Scenario]

# Recovery steps

---

Critical Warnings

1. NEVER [prohibition]
2. NEVER [prohibition]

---

File Structure

project/
├── required-file.ext
└── directory/
    └── config.json

---

Related Documentation

• [Link to related guide]
• [Link to reference]

---

## 🧪 Testing Your Guide

### Machine-Actionability Checklist

- [ ] **CLAUDE-CONTEXT block** present and complete
- [ ] **Decision logic** explicitly stated with conditions
- [ ] **Pre-execution checks** validate all prerequisites
- [ ] **Commands** include expected output examples
- [ ] **Error messages** mapped to solutions
- [ ] **File paths** are absolute or clearly relative to stated directory
- [ ] **State detection** methods provided
- [ ] **Variables** clearly marked as placeholders
- [ ] **Exit codes** documented where relevant

### Human Readability Checklist

- [ ] **Visual hierarchy** with emojis and formatting
- [ ] **Progressive disclosure** from overview to details
- [ ] **Scannable** with clear sections and headings
- [ ] **Examples** provided alongside abstractions
- [ ] **Context** given before commands
- [ ] **Purpose** clear for each section
- [ ] **Navigation** aided by table of contents or structure

### Validation Process

1. **Claude Test**: Have Claude read and explain the guide
2. **Execution Test**: Run commands in dry-run mode
3. **Human Review**: Quick 30-second scan test
4. **Error Test**: Trigger errors and verify recovery works

---

## 📚 Pattern Library

### Authentication Check Pattern

```markdown
## 🔐 Authentication Setup

```bash
# Check for credentials
[ -f .env ] && source .env || { echo "✗ Missing .env"; exit 1; }
[ -n "$API_KEY" ] || { echo "✗ API_KEY not set"; exit 1; }

# Validate credentials
curl -s -H "Authorization: Bearer $API_KEY" https://api.example.com/validate | \
  grep -q "authenticated" && echo "✓ Authenticated" || echo "✗ Invalid credentials"

### File Validation Pattern

```markdown
## 📄 Configuration Validation

```bash
# Check file exists and is valid JSON
CONFIG="config.json"
[ -f "$CONFIG" ] || { echo "✗ Missing $CONFIG"; exit 1; }
jq '.' "$CONFIG" >/dev/null 2>&1 || { echo "✗ Invalid JSON in $CONFIG"; exit 1; }
echo "✓ Configuration valid"

### Deployment Pattern

```markdown
## 🚀 Safe Deployment

```bash
# 1. Backup current state
./backup.sh current-state

# 2. Dry-run deployment
./deploy.sh --dry-run || { echo "✗ Dry-run failed"; exit 1; }

# 3. Get confirmation
read -p "Proceed with deployment? (y/N): " -n 1 -r
echo
[[ $REPLY =~ ^[Yy]$ ]] || { echo "Cancelled"; exit 0; }

# 4. Execute deployment
./deploy.sh && echo "✓ Deployed successfully"

# 5. Verify deployment
./health-check.sh || ./rollback.sh current-state

---

## ❌ Anti-Patterns to Avoid

### 1. Ambiguous Instructions

**Bad**: "Configure the service appropriately"  
**Good**: "Set PORT=3000 and NODE_ENV=production in .env file"

### 2. Missing Prerequisites

**Bad**: `./deploy.sh`  
**Good**: 
```bash
# Prerequisites: .env file with API_KEY, config.json validated
[ -f .env ] && [ -f config.json ] || exit 1
./deploy.sh

3. No Expected Output

Bad: "Run the test command"
Good:

./test.sh
# Expected: "✓ All tests passed (42 tests in 1.2s)"

4. Relative Paths Without Context

Bad: "Edit the config file"
Good: "Edit /project/config/settings.json (relative to project root)"

5. Missing Error Handling

Bad: "If it fails, try again"
Good:

# If you see "Connection refused", run:
./reset-connection.sh && sleep 5 && ./retry.sh

---

Examples of Excellence

From Our Codebase

1. Sliplane API Management Guide

   • Excellent CLAUDE-CONTEXT block
   • Clear decision matrices
   • Complete error recovery patterns

2. Beautiful Documentation Design Guide

   • Strong visual hierarchy
   • Good progressive disclosure
   • Effective use of examples

3. Testing Framework Guide

   • Clear structure and organization
   • Good balance of theory and practice
   • Comprehensive checklist approach

---

Quick Start: Your First Guide

1. Copy the template from the Complete Guide Template section
2. Fill in CLAUDE-CONTEXT with your specific context
3. Define decision logic for common user requests
4. Add pre-execution checks for all prerequisites
5. Document commands with expected outputs
6. Map errors to solutions in recovery section
7. Add critical warnings for dangerous operations
8. Test with Claude and a human reader
9. Iterate based on actual usage

---

Summary

Writing machine-actionable and human-readable documentation requires:

1. Dual-channel thinking - Every element serves both audiences
2. Explicit context - Never assume, always state
3. Complete examples - Show, don't just tell
4. Error awareness - Plan for failure, provide recovery
5. Visual organization - Help humans scan, help machines parse
6. Progressive enhancement - Basic instructions enhanced for each audience
7. Safety first - Critical warnings and validation before execution

Remember: A guide succeeds when Claude can execute it reliably AND a human can understand it in 30 seconds.

---

This meta-guide establishes the standards for all operational documentation in the Sasha project. Follow these patterns to create documentation that truly serves both machines and humans.