how-to-talk-to-claude/PROJECT-CONTEXT.md

"How to Talk to Claude" Project Context & Style Guide

Project Overview

Project Name: How to Talk to Claude - A Comprehensive AI Collaboration Guide Current Location: /home/user/claude/how-to-ai-fresh/ Development Server: http://localhost:4321 Technology Stack: Astro + Starlight with custom CSS and full component system

Project Philosophy & Tone

Core Voice & Style

• Conversational and human-centered - Written like explaining to a friend, not a manual
• Experience-driven - Focus on actual collaboration experiences, not just theory
• Problem-focused - Address real frustrations people have with AI
• Inclusive and accessible - Examples work across different tech backgrounds
• Psychologically aware - Acknowledge emotional aspects of learning AI collaboration
• Authentic over generic - Avoid typical "AI prompt" advice, focus on genuine partnership

Content Approach

• No jargon or technical complexity unless absolutely necessary
• Conversational examples over formal templates
• Personal anecdotes and relatable analogies (AIM, texting, coffee shop interactions)
• Honest about limitations - acknowledge when things don't work
• Practical and immediately useful - every section provides actionable value

Content Framework: Diataxis Implementation

We use the Diataxis documentation framework with four distinct content types:

🎓 Tutorials (Learning-oriented)

• Purpose: Step-by-step experiences that build confidence through practice
• User mindset: "I want to learn by doing"
• Structure: Guided experiences with actual conversations
• Voice: Encouraging, supportive, "let's try this together"

🔧 How-To Guides (Task-oriented)

• Purpose: Solutions for specific problems users face right now
• User mindset: "I have a specific problem to solve"
• Structure: Problem → Solution → Examples → Links to related content
• Voice: Direct, practical, "here's how to fix this"

🧠 Explanations (Understanding-oriented)

• Purpose: Principles and psychology behind effective AI collaboration
• User mindset: "I want to understand why this works"
• Structure: Concept → Psychology → Examples → Implications
• Voice: Thoughtful, exploratory, "here's what's happening underneath"

⚡ Quick Reference (Information-oriented)

• Purpose: Conversation starters, troubleshooting, emergency fixes
• User mindset: "I need something fast"
• Structure: Scannable, organized by problem type, lots of templates
• Voice: Concise, organized, "bookmark this for when you need it"

Component Usage Standards

Visual Hierarchy:

• Use CardGrid for feature organization and comparisons
• Use Tabs for before/after examples and alternatives
• Use Code blocks for conversation examples with context
• Use Asides for tips, warnings, insights (4 types: note, tip, caution, danger)
• Use Steps for sequential processes and workflows
• Use LinkCards for enhanced navigation between guides
• Use Badges for visual indicators and status

Content Enhancement Patterns:

• Start sections with clear Aside callouts for key insights
• Use Tabs to show contrasts (good vs bad examples)
• Group related information in Card layouts
• End sections with LinkCard navigation to related content
• Use Code blocks for all conversation templates and examples

Current Project Status

✅ Complete Sections (Beginners Guide)

• 3 Tutorials: First conversation, messy ideas, creative collaboration
• 13 How-To Guides: Organized into Communication & Style, Information & Research, Creative & Personal, Advanced Techniques
• 4 Explanations: Conversations vs commands, psychology, how Claude thinks, making AI work for life
• 1 Quick Reference: Comprehensive conversation starters and troubleshooting

🚀 Framework Ready (Intermediate Guide)

• Complete structure with 27 content placeholders
• 5 Tutorial outlines for advanced collaboration
• 16 How-To Guide outlines organized into 4 categories
• 6 Explanation outlines for sophisticated concepts
• 1 Advanced Reference outline for power users

🎨 Technical Implementation

• All 54 content files converted to MDX format with component support
• Complete Starlight integration with custom CSS and navigation
• Logo integration and professional branding
• All internal links properly functioning with /beginners/ prefix
• Two-tier navigation system (Beginners/Intermediate)

Git Commit History

• 5da77a3 - Initial complete conversion (11,697 lines)
• 0d6fea5 - Homepage title fix
• fab2254 - Major restructure into two guides
• 2925a43 - Logo branding enhancement
• 428a3a4 - Complete Intermediate Guide outline (27 placeholders)
• ad62547 - Enable Starlight components (54 files converted to MDX)
• 91225f7 - Enhanced Introduction & Ask When Uncertain pages
• 97de83f - Transformed Quick Reference (+374 lines of rich components)
• 907364b - Repair all internal links after /beginners/ restructure

Key Success Patterns

Content Enhancement Strategy

1. Start with most-visited content (homepage, introduction, popular how-to guides)
2. Use components strategically - enhance scannability and engagement
3. Maintain conversational voice while adding visual structure
4. Create clear navigation paths between related content
5. Focus on user problems rather than technical features

Component Integration Best Practices

• Import components at top of each enhanced file
• Use CardGrid for organizing multiple related concepts
• Use Tabs for showing different approaches or examples
• Use Asides for important callouts and tips
• End sections with LinkCard navigation to related content
• Always maintain the human, conversational tone within component structure

This approach has transformed basic markdown content into professional, interactive documentation while preserving the authentic, human-centered voice that makes this guide special.