Add new blog post: Forty Years of Code, Still Can't Type
Personal reflection on impostor syndrome and neurodivergent coding experience. Discusses 40+ years of self-taught development while struggling with mechanical typing precision, the unsustainable "code frenzies" coping mechanism, and how AI-assisted development (Claude Code) eliminated the transcription bottleneck. Also updates CLAUDE.md with comprehensive voice and style guide for future writing assistance. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
135
CLAUDE.md
135
CLAUDE.md
@@ -75,4 +75,137 @@ The site has four menu groups configured in `config.toml`:
|
||||
|
||||
- The Hugo server automatically watches for changes in `/archetypes`, `/assets`, `/content`, `/data`, `/layouts`, `/static`, and `/themes`
|
||||
- Posts are created with draft status by default (controlled by archetype)
|
||||
- The site integrates with multiple social platforms and services in the Kestrel's Nest ecosystem
|
||||
- The site integrates with multiple social platforms and services in the Kestrel's Nest ecosystem
|
||||
|
||||
## Eric's Writing Voice & Style Guide
|
||||
|
||||
When writing or editing blog posts, maintain Eric's distinctive voice and structural patterns:
|
||||
|
||||
### Structural Patterns
|
||||
|
||||
1. **Opening Elements**
|
||||
- Start with an italicized tagline that captures the core insight (e.g., "_Three thousand passing tests don't mean your system works_")
|
||||
- Include a TL;DR section early in technical posts, using callout boxes for key summaries
|
||||
- Use horizontal rules (`---`) to separate major sections
|
||||
|
||||
2. **Callout Boxes** (use Hugo shortcode syntax)
|
||||
- Extensively use callout boxes for warnings, examples, quotes, and key insights
|
||||
- Types: `info`, `warning`, `success`, `danger`, `note`, `quote`, `example`
|
||||
- These are structural signposts, not decoration—they highlight critical information
|
||||
- Example: `{{< callout type="info" title="Why This Matters" >}}...{{< /callout >}}`
|
||||
|
||||
3. **Section Structure**
|
||||
- Use numbered breakdowns for complex topics (Bug Category #1, #2, etc.)
|
||||
- End sections with concrete metrics or results
|
||||
- Include "What's Next" or forward-looking sections in series posts
|
||||
|
||||
### Tone & Voice Characteristics
|
||||
|
||||
1. **Brutal Honesty with Technical Confidence**
|
||||
- Be unflinchingly honest about failures and mistakes
|
||||
- Never self-pitying—own mistakes but frame as learning
|
||||
- Mix emotional vulnerability with technical precision
|
||||
- Examples: "The Most Embarrassing Bug," "My morale was at an all-time low" paired with detailed technical analysis
|
||||
|
||||
2. **Concrete Over Abstract**
|
||||
- Always ground statements in specific numbers, metrics, and examples
|
||||
- Replace abstract lists with detailed scenarios showing actual time breakdowns
|
||||
- Use real project names (LocallyGrown.net) and specific technologies (Rails, SvelteKit, Claude Code)
|
||||
- Before/after comparisons with actual measurements: "8-12 commits per week" → "40-50 commits per week"
|
||||
|
||||
3. **Show the Work**
|
||||
- Include code snippets (even wrong code) with explanations
|
||||
- Provide specific numbers: "314 commits in 18 days," "$1.3 million in annual sales"
|
||||
- Show actual dialogue or process breakdowns
|
||||
- Time breakdowns: "Total: 25 minutes. The thinking took 2. The transcription took 23."
|
||||
|
||||
4. **Characteristic Phrases**
|
||||
- "Here's what matters:"
|
||||
- "The numbers tell the story:"
|
||||
- "The real X was always Y"
|
||||
- "This wasn't about X. It was about Y."
|
||||
- Rhetorical questions followed by answers
|
||||
- Extensive parenthetical asides: "(after comparing Prisma, TypeORM, and others)"
|
||||
|
||||
5. **Human Impact Focus**
|
||||
- Always circle back to impact on real people—users, customers, communities
|
||||
- Frame personal victories as community victories
|
||||
- End with forward-looking perspective, not just resolution
|
||||
- Connect technical decisions to human consequences
|
||||
|
||||
6. **Technical Communication**
|
||||
- Never assume reader is technical—explain even when showing code
|
||||
- Balance technical specifics with human impact
|
||||
- Use technical details to prove points, not to show off
|
||||
- Include both the code AND the why
|
||||
|
||||
### Content Patterns
|
||||
|
||||
1. **Examples Over Explanation**
|
||||
- Transform abstract concepts into concrete scenarios
|
||||
- Show specific workflows with timing breakdowns
|
||||
- Include real-world examples from actual projects
|
||||
- Use before/after comparisons with measurable differences
|
||||
|
||||
2. **Data-Driven Narratives**
|
||||
- Support claims with specific metrics
|
||||
- Track and report actual measurements
|
||||
- Use Git logs, analytics, user counts as evidence
|
||||
- Quantify time savings, performance improvements, impact
|
||||
|
||||
3. **Acknowledgment & Gratitude**
|
||||
- Credit others extensively (market managers, designers, contributors)
|
||||
- Acknowledge tools and their creators
|
||||
- Recognize community contributions
|
||||
- Human names for AI agents (Ray, Agatha, Ada) to maintain human-centered perspective
|
||||
|
||||
4. **Balanced Disclaimers**
|
||||
- Use callout boxes for important context or disclaimers
|
||||
- Acknowledge different approaches work for different people
|
||||
- "What This Isn't" sections to clarify boundaries
|
||||
- Respectful of different working styles and tools
|
||||
|
||||
### Series & Long-Form Posts
|
||||
|
||||
For multi-part series (like the LocallyGrown series):
|
||||
|
||||
- Include series navigation at the end
|
||||
- Link to related posts with clear context
|
||||
- Use consistent callout styles across the series
|
||||
- Build narrative arc across posts
|
||||
- Reference earlier posts when relevant
|
||||
|
||||
### Example Transformations
|
||||
|
||||
**Abstract → Concrete:**
|
||||
|
||||
Before: "Most of my time was spent on mechanical tasks"
|
||||
|
||||
After: "I tracked it once: 4 hours of actual coding work produced 3.5 hours of fixing typos, hunting syntax, and triple-checking. The ratio was backwards."
|
||||
|
||||
**General → Specific:**
|
||||
|
||||
Before: "The platform performs well"
|
||||
|
||||
After: "Response times are consistently under 2 seconds, even during peak Sunday night ordering when 200+ customers are browsing simultaneously."
|
||||
|
||||
**Personal → Community:**
|
||||
|
||||
Before: "I finally solved the problem"
|
||||
|
||||
After: "The fix went live Tuesday morning. By Wednesday, three market managers reported their volunteers could finally access the tools they needed. Physical workflow restored."
|
||||
|
||||
### Voice Checklist for Posts
|
||||
|
||||
- [ ] Opens with italicized tagline
|
||||
- [ ] Includes TL;DR with metrics (for technical posts)
|
||||
- [ ] Uses 2-4 callout boxes for key insights
|
||||
- [ ] Contains specific numbers and measurements
|
||||
- [ ] Shows concrete examples, not just abstractions
|
||||
- [ ] Balances vulnerability with technical confidence
|
||||
- [ ] Includes impact on real people/communities
|
||||
- [ ] Ends with forward-looking perspective
|
||||
- [ ] Credits others and acknowledges contributions
|
||||
- [ ] Uses characteristic phrases ("Here's what matters," "The numbers tell the story")
|
||||
|
||||
This voice reflects someone who is deeply technical, brutally honest about challenges, focused on real-world impact, and committed to serving communities—not just building software.
|
||||
Reference in New Issue
Block a user