Developer Communication Guide

# Documentation Types
DOCUMENTATION_TYPES = {
    "api_docs": {
        "audience": "Other developers",
        "content": [
            "Endpoint descriptions",
            "Request/response formats",
            "Authentication",
            "Error codes",
            "Examples"
        ],
        "tools": ["Swagger", "OpenAPI", "Docusaurus"]
    },
    "readme": {
        "audience": "Developers using your code",
        "content": [
            "What it does",
            "How to install",
            "How to use",
            "Examples",
            "Contributing"
        ],
        "template": "Standard README template"
    },
    "architecture": {
        "audience": "Team leads, stakeholders",
        "content": [
            "Overview",
            "Components",
            "Data flow",
            "Decisions made",
            "Trade-offs"
        ],
        "tools": ["Diagrams.net", "Mermaid", "Draw.io"]
    }
}

# Comment Best Practices
COMMENT_GUIDE = {
    "good_comments": [
        "Explain WHY, not WHAT",
        "Document complex algorithms",
        "Note non-obvious decisions",
        "Reference external sources"
    ],
    "bad_comments": [
        "State the obvious",
        "Comment out code",
        "Leave TODO without explanation",
        "Be sarcastic or unprofessional"
    ],
    "example_good": """
    # Using binary search because we need O(log n) lookup
    # rather than O(n) for large datasets
    def find_index(sorted_list, target):
        # Implementation
    """,
    "example_bad": """
    # This is a function that finds something
    def find(something):
        # Find the thing
    """
}

# Effective Code Presentation
CODE_PRESENTATION = {
    "before": {
        "prepare": "Rehearse your demo multiple times",
        "simplify": "Reduce to essential parts",
        "highlight": "Use annotations or highlights",
        "backup": "Have recording as fallback"
    },
    "during": {
        "pace": "Don't rush through code",
        "explain": "Narrate what you're doing",
        "interact": "Ask questions to engage",
        "pause": "Let people process"
    },
    "tools": {
        "live": "VS Code with Vim/Emacs plugins",
        "slides": "Slides with code blocks",
        "recorded": "Code video with voiceover"
    }
}

# Simplification Techniques
EXPLANATION_TECHNIQUES = {
    "analogies": {
        "description": "Use familiar concepts",
        "example": "Like a library catalog, indexes help find data quickly"
    },
    "layering": {
        "description": "Start high-level, then detail",
        "structure": ["Overview", "Components", "Details"]
    },
    "visuals": {
        "description": "Use diagrams and drawings",
        "tools": ["Whiteboard", "Diagrams", "Animations"]
    },
    "storytelling": {
        "description": "Frame as a narrative",
        "elements": ["Problem", "Solution", "Journey", "Outcome"]
    }
}

# Async Communication Best Practices
ASYNC_GUIDELINES = {
    "emails": {
        "subject": "Clear, specific, actionable",
        "body": "SCQA format (Situation, Complication, Question, Answer)",
        "structure": "Bullet points for long content",
        "action": "Explicitly state what you need"
    },
    "slack": {
        "channels": "Use appropriate channels",
        "threads": "Keep discussions in threads",
        "urgent": "Only use for true urgent items",
        "formatting": "Use code blocks for code"
    },
    "docs": {
        "where": "Use docs, not chat, for decisions",
        "why": "Future-you and others will thank you",
        "how": "Include context and reasoning"
    }
}

# Effective Meeting Types
MEETING_TYPES = {
    "daily_standup": {
        "duration": "15 minutes max",
        "format": "What did, What doing, Blockers",
        "remote": "Async updates acceptable"
    },
    "code_review": {
        "duration": "30-60 minutes",
        "focus": "Architecture, logic, patterns",
        "avoid": "Syntax discussions"
    },
    "planning": {
        "duration": "60-120 minutes",
        "preparation": "Come with initial estimates",
        "outcome": "Prioritized backlog"
    },
    "retrospective": {
        "duration": "60 minutes",
        "format": "What went well, What didn't, Actions",
        "follow_through": "Assign owners to actions"
    }
}

# Communicating with Non-Technical Stakeholders
STAKEHOLDER_GUIDE = {
    "audiences": {
        "executives": {
            "focus": "Business value, ROI, risks",
            "language": "Avoid jargon",
            "format": "Summaries, dashboards, demos"
        },
        "product_managers": {
            "focus": "Feasibility, timeline, scope",
            "language": "Technical but accessible",
            "format": "Estimates, trade-offs"
        },
        "clients": {
            "focus": "What they need to know",
            "language": "Non-technical",
            "format": "Updates, demos, training"
        }
    },
    "tips": [
        "Ask what they need to know",
        "Lead with outcomes",
        "Be prepared for questions",
        "Follow up in writing"
    ]
}