Claude Markdown Documentation Standards Guide

Generated: 2025-07-24 15:30 UTC
Status: Complete
Verified:

Overview

This guide provides comprehensive standards and best practices for Claude instances when creating markdown documentation. It consolidates all conventions, requirements, and patterns for consistent, high-quality documentation across projects.

Core Documentation Principles

1. Clarity and Conciseness

• Write for your audience's technical level
• Minimize output tokens while maintaining helpfulness
• Answer queries directly without unnecessary preamble
• Use 1-3 sentences when possible

2. Verification Standards

• Mark all information as either verified () or speculated ()
• Include sources for verified information
• Clearly indicate assumptions
• Use clear status indicators throughout documents

Document Structure Standards

Required Header Format

# Document Title

**Generated**: YYYY-MM-DD HH:MM UTC
**Status**: Draft/In Progress/Complete
**Verified**: ✅ (for verified information) / ❓ (for speculated information)

## Overview
Brief description of document contents and purpose

Section Organization

1. Title (H1)
2. Metadata block
3. Overview section
4. Main content sections with logical flow
5. Cross-references and links
6. No Document History section (explicitly excluded)

File Naming Conventions

Standard Patterns

Special Cases

• Temporary files: Include "temp" in filename
• Screenshots: @docs/product-requirements/Screenshot YYYY-MM-DD at HH.MM.SS.png
• All MD docs go under /docs directory in relevant folders

Content Requirements

Visual Elements

Mermaid Diagrams

Include diagrams where they help explain complex concepts:

Diagram Standards:

• Use consistent node naming
• Add clear labels
• Include flow direction
• Keep diagrams focused on single concepts

Code Examples

Proper Formatting

// ✅ Good: Clear, contextual example
async function processDocument(file) {
    const content = await parseFile(file);
    return convertToMarkdown(content);
}

// ❌ Bad: Missing context and error handling
function process(f) {
    return convert(parse(f));
}

Tables

Use tables for structured data with proper alignment:

Linking Standards

Internal Links

• Link to existing MD documents: [See API Guide](./api-guide.md)
• Use relative paths for project documents
• Verify links are valid before including

External Links

• Use descriptive link text: [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/)
• Never use "click here" or bare URLs
• Include context for why the link is relevant

Technical Writing Guidelines

Lists

Unordered Lists (for non-sequential items):

• Docker containerization
• AWS Lambda functions
• PostgreSQL database

Ordered Lists (for sequential steps):

1. Install dependencies
2. Configure environment
3. Run deployment script

Command Documentation

Always include clear command examples:

# Build and deploy (include description)
sam build
sam deploy --no-confirm-changeset

# Local testing with context
sam local start-api --port 3001 --env-vars env.json

Project-Specific Considerations

Document Conversion Focus

• Emphasize optimization for AI processing
• Remove generation metadata unless specifically needed
• Focus on clean, parseable output

Security Best Practices

• Never include credentials or sensitive data
• Use placeholder values for examples
• Document security implications clearly

Performance Documentation

• Include performance implications
• Document resource requirements
• Note scalability considerations

Quality Checklist

Before finalizing any document, verify:

• Header includes all required metadata
• File follows naming conventions
• All information marked as verified or speculated
• Code examples are complete and tested
• Links are valid and descriptive
• No unnecessary metadata or history sections
• Diagrams included where helpful
• Cross-references to related documents
• Clear, concise writing style
• Proper markdown formatting throughout

Common Patterns to Follow

API Documentation Structure

## Endpoint: /convert/xlsx

**Method**: POST  
**Content-Type**: multipart/form-data

### Request
- **file**: Excel file (required)
- **format**: Output format (optional)

### Response
```json
{
    "markdown": "converted content",
    "status": "success"
}

### Error Documentation
```markdown
### Common Errors

| Error Code | Description | Solution |
|------------|-------------|----------|
| 400 | Invalid file format | Ensure file is .xlsx |
| 413 | File too large | Limit files to 5MB |
| 500 | Processing error | Check file contents |

Git Commit Practices

When documenting changes:

• Commit after material changes or milestones
• Use descriptive commit messages
• Include documentation updates with code changes
• Archive unused files with clear naming

Maintenance Guidelines

Regular Updates

• Update when systems change
• Review for accuracy quarterly
• Remove outdated information
• Add new patterns as discovered

Version Control Integration

• Track all documentation in git
• Use meaningful commit messages
• Group related documentation changes
• Archive outdated docs appropriately

Summary

This guide ensures consistent, high-quality markdown documentation across all Claude instances. Following these standards creates documentation that is:

• Clear and accessible
• Properly structured
• Visually enhanced with diagrams
• Technically accurate
• Optimized for AI processing
• Maintainable over time

Remember: Focus on clarity, verify information, and maintain consistent formatting throughout all documentation.