# "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.