Skip to content

STYLE_GUIDE.md

Latest commit

 

History

History
68 lines (52 loc) · 2.67 KB

STYLE_GUIDE.md

File metadata and controls

68 lines (52 loc) · 2.67 KB

Cloud Artisan Writing Style Guide: Tone & Voice

This is the writing style guide to ensure consistent tone and voice when preparing and reviewing posts.

Core Voice Characteristics

Conversational & Personal

  • Write in first person extensively ("I want to find", "I was hoping", "In my experience")
  • Direct address to reader using "you"
  • Share personal reactions and experiences
  • Use rhetorical questions to engage readers

Honest & Transparent

  • Admit limitations and unknowns openly
  • Discuss failures and problems candidly
  • Be realistic about challenges and trade-offs
  • Share both successes and frustrations

Playful & Humorous

  • Use casual interjections ("mmkay", "Happy days!")
  • Include self-deprecating humor
  • Use italics for emphasis and dramatic effect
  • Playful exaggeration when appropriate ("I will bear your man-babies!")

Language Patterns

Casual Expressions

  • "Let's face it"
  • "Here's why..."
  • "Here's the thing:"
  • "Honestly, it was fun"
  • "Unfortunately"
  • "Fortunately"

Engagement Techniques

  • Parenthetical asides for reader connection
  • Direct questions to the reader
  • Conversational transitions
  • Acknowledgment of reader's likely thoughts

Technical Communication

  • Explain complex topics accessibly
  • Include specific numbers and examples
  • Provide actionable, practical advice
  • Reference real projects and experiences

Examples from Original Posts

Personal & Conversational:

"I was hoping to find existing surveys/questionnaires that can be reused to perform audits on cloud service providers. I was also hoping those audits could be performed without introducing much additional load for the auditor or the cloud service providers. Especially for the auditor... because, no doubt, that will be me."

Honest & Direct:

"Unfortunately, I had to migrate one of my projects from Google App Engine to Django on a self-managed server. I didn't want to do this."

Humorous & Engaging:

"Try explaining to your partner that some crazy ephemeral stuff happened somewhere on the Internet and now you can't afford the mortgage payment."

Experience-Driven:

"RightScale have some tutorials on using their service to set up auto-scaling. Recently I played around with it, configuring auto-scaling in response to increases and decreases in server load. Honestly, it was fun. But it was essentially a folly, an exercise in dealing unnecessarily with dangerous corner cases."

Application Guidelines

  • Start with personal motivation or context
  • Share real experiences and lessons learned
  • Use humor to lighten technical content
  • Be direct about problems and solutions
  • End with engagement or call to action
  • Keep the reader in mind throughout