Writing Style Guide

• Use gender-neutral language
  • E.g. “The manager is assigned a role, and they have access to a resource”
• Be consistent with capitalization
  • Lower-case headlines, except proper nouns
    • E.g. The pros and cons of updatable views in PostgreSQL
  • Capitalize proper nouns
    • E.g. Google Docs, JSON, Postgres, Slack, Hacker News
  • Don’t capitalize non-proper nouns
    • E.g. authorization, organization
• Be beginner-friendly
  • EAOFU (Expand acronyms on first use)
  • Avoid words like “obviously”
• Use friendly language; avoid formal or academic phrasing
• Use backtick markup for code terms
  • E.g. user_id
• Write non-technical numbers 1-100 as text
  • E.g. five, ninety-nine
• Avoid "very"
• Edit phase:
  • Shorten phrases to improve them
    • E.g. “However, at the same time, it’s a very powerful language” --> “At the same time, it’s a powerful language”
  • Convert passive phrasing to active
    • E.g. “It was designed to have beginner-friendly syntax, so it’s easy and fun to use” --> “Beginner-friendly syntax makes it easy and fun to use”
  • Paste your article into Grammarly or Hemingway App to:
    • Check for spelling, grammar, and punctuation errors
    • Consider style suggestions
  • Place commas where there are pauses in speech
    • E.g. “In this post,” | “For example,” | “However,”
• Content
  • Title and intro should hook the reader. Why should they care?
  • Conclusion should say how the reader’s world has changed after reading this, and what the next steps are. Have a clear call to action for readers.