Voice and Tone

Guidelines and examples for writing in jonmagic's authentic voice across all formats—from technical documentation to personal reflections.

Core Voice Characteristics

• First-person narratives with introspective framing
• Thoughtful principal-engineer perspective grounded in real stories
• Concise paragraphs (2–4 sentences) with mixed sentence lengths
• Actionable advice balanced with reflective insight
• Show humility and optimism—acknowledge uncertainty, emphasize learning
• Credit collaborators by handle (@alice) and mention teams/products explicitly

Sentence Construction

• Vary sentence length: Mix short declarative statements with longer reflective ones
• Start with insight: "This semester taught me...", "What I learned:", "The pattern across..."
• Use concrete examples: Specific numbers when meaningful (90% reduction, 36-hour incident)
• Avoid jargon inflation: Prefer simple words; use technical terms only when necessary
• Show, don't tell: Use accomplishments as evidence, not just claims

Paragraph Patterns

1. Opening hook: Lead with the "so what" or meta-insight
2. Context setting: Why this work mattered (organizational or human dimension)
3. Approach description: How you did it, who you worked with
4. Outcome statement: What changed, who benefited
5. Learning extraction: What was learned (in reflective pieces)

Common Structures

Problem-Solution-Learning

Problem: I was drowning in meetings, losing track of decisions...
Solution: Then I found a better way—capture once, reuse everywhere with AI.
Learning: The act of reflection was building understanding in my own mind.

Empathy-Truth-Action

Empathy: Earlier today I saw a friend post about layoffs...
Truth: I've watched this cycle play out more times than I can count...
Action: So how do I deal with this reality? I accept it, and I prepare.

Discovery-Insight-Forward

Discovery: Two things shifted my approach...
Insight: Not all tasks exist to produce an output. Some exist to build understanding.
Forward: The skill that endures isn't "knowing X" but "designing collaborations..."

What to Avoid

• Generic claims: "Improved performance" → "Reduced re-renders by 90%, cutting codebase in half"
• Passive voice: "The system was improved" → "I redesigned the system"
• Activity lists: Don't just list PRs; tell the story
• Perfectionism: Acknowledge gaps and uncertainties
• Bold prefixes: Avoid "Ship: ..." style formatting; start bullets directly with content

Lists and Bullets

• Use numbered lists for sequential steps or guidelines learned over time
• Use bullet lists for parallel ideas, examples, or quick references
• Introduce lists with context before diving in
• Keep bullets concise (one-sentence ideal, sometimes two for complex ideas)
• No bold/italic in bullets unless emphasizing a specific term

Crediting and Collaboration

• Always cite collaborators: @alice, @bob
• Give credit generously: "My coworker John (@jnunemaker) has been encouraging me..."
• Show collaborative process: "The nineteen review comments showed the design process worked"
• Acknowledge influence: "A close teammate and friend @kmcq gave this advice..."

Metrics and Numbers

Use metrics when they show:

• Dramatic change: 90% reduction, 10x improvement
• Human impact: 650k → 60k queue entries (shows morale improvement)
• Time pressure: 36-hour incident, 2-hour bug fix
• Reach: 19 review comments, 8000 blog views
• Persistence: 26 weekly cycles, 95 daily logs

Frame metrics around people:

• Not: "Reduced queue size by 90%"
• But: "Reduced queue from 650k to 60k entries, giving analysts a manageable queue they could make progress on"

Format-Specific Guidance

Blog Posts

• Lead with a hook that captures transformation or key insight
• Use rhetorical questions sparingly to invite reflection
• Include concrete examples with dates, numbers, links
• End forward-looking with "what's next" or actionable takeaways

Snippets & Reflections

• Ships: Lead with business impact first, then technical work
• Collaborations: Focus on HOW you collaborated, integrate names naturally
• Risks/Challenges: Show transformation from problem to capability
• Be specific with dates, PR numbers, and links

Feedback

• Address to the person directly (Name, not "Name...")
• Balance strengths with growth opportunities
• Use concrete examples from their work
• Frame growth as opportunity, not criticism

Technical Documentation

• Start with the problem/context
• Provide step-by-step clarity
• Include code examples or commands
• End with next steps or related resources

Writing Samples

See writing-samples.md for extensive examples from recent posts demonstrating these patterns in practice.