Skip to content

STYLE.md

Latest commit

 

History

History
97 lines (70 loc) · 5.1 KB

STYLE.md

File metadata and controls

97 lines (70 loc) · 5.1 KB

STYLE.md: Writing Guide for devin.fitzsky.com

Voice & Tone

  • First person, casual. Write like a dev journal. "I built this," "I ran into," "here's what I found."
  • Technical audience. Assume the reader is a developer or engineer. Don't over-explain basics, but do go deep on the interesting parts.
  • Detail matters. Show the commands, the config, the error messages. Readers want to learn from what actually happened, not a summary.
  • Conversational, not corporate. No marketing speak. No "leverage" or "utilize." Write like you're telling a friend about a project.
  • Confident and direct. State things plainly. Skip hedging ("it might potentially be useful to consider...").
  • Light humor when it fits. Dry, understated. Never forced.

Structure

  • No rigid template. Each post finds its own shape. Some are walkthroughs, some are reflections, some are deep dives.
  • Short paragraphs. 2-4 sentences typical. Let the writing breathe.
  • Headers as signposts, not decoration. Use them when the topic genuinely shifts.
  • Code and config inline. Use fenced code blocks for commands, snippets, config. Backticks for inline references (main, bundle exec jekyll serve).
  • End naturally. Don't force a conclusion or CTA. A closing thought, a question, or just stopping when you're done. All fine.

What NOT to Do

  • Don't write intros that restate the title ("In this blog post, I will discuss...")
  • Don't use bullet lists as a crutch -- narrative paragraphs for the main body, lists for genuinely list-shaped things
  • Don't pad posts. If it's a short topic, write a short post
  • Don't use stock/generic headers like "Introduction" or "Conclusion"
  • Don't write in third person or use "we" (unless genuinely collaborative)

AI-Slop Avoidance

This section exists because AI writing has a recognizable smell. Every item below is banned.

Punctuation

  • No em dashes. Use commas, parentheses, colons, or just split the sentence. Never use — or -- as a parenthetical.

Banned Words

These words are AI-frequency outliers. Don't use them at all:

delve, leverage, utilize, harness, streamline, foster, underscore, bolster, embark, unlock, unveil, elevate, empower, cultivate, facilitate, orchestrate, spearhead, reimagine, transcend, resonate, encompass, garner, showcase, exemplify, supercharge, unleash

pivotal, robust, innovative, seamless, multifaceted, nuanced, comprehensive, cutting-edge, transformative, groundbreaking, profound, meticulous, intricate, compelling, unwavering, unparalleled, indelible, commendable, bespoke, paramount, daunting, whimsical, bustling, vibrant, dynamic, esteemed, insightful, noteworthy

landscape, tapestry, realm, journey, beacon, testament, synergy, paradigm, interplay, intricacies, underpinnings, crucible, labyrinth, enigma, mosaic, treasure trove, nexus, ethos

meticulously, effortlessly, arguably, undoubtedly, notably, crucially, fundamentally, inherently, inevitably, indeed

Banned Phrases

  • "In today's [anything]"
  • "In the ever-evolving..."
  • "In a world where..."
  • "It's worth noting that..."
  • "It's important to note..."
  • "This is particularly true..."
  • "Let's dive in" / "Let's delve into"
  • "Here's the thing:"
  • "Here's why that matters"
  • "Make no mistake"
  • "Let that sink in."
  • "At the end of the day..."
  • "Game changer"
  • "Deep dive"
  • "Serves as a powerful reminder"
  • "Serves as a testament"
  • "Navigate the complexities of"
  • "Harness the power of"
  • "Unique blend"
  • "As mentioned earlier"

Banned Transitions

Don't start sentences with: Furthermore, Moreover, Additionally, Consequently, Nevertheless, Nonetheless, Subsequently, Indeed, Notably. Just write the next sentence.

Structural Tells to Avoid

  • No binary setups. "Not X. But Y." and "It's not about X. It's about Y." are AI cliches.
  • No forced tricolons. Lists of exactly three adjectives or phrases are a pattern. Vary it.
  • No rhetorical question + immediate answer. "So what does this mean? It means..." is a giveaway.
  • No section summaries. Don't recap what you just said at the end of a section.
  • No false agency. Don't attribute human actions to abstractions ("the data tells us," "the market rewards").
  • No relentless positivity. Not everything is "exciting" or "truly remarkable." Be honest about tradeoffs.
  • No meta-commentary. Don't refer to the structure of the post ("In this article, we'll explore...").

Topics

The blog covers whatever Devin finds interesting enough to write about. Software, systems, infrastructure, tooling, dev workflows, design decisions, things learned the hard way. Not limited to any product or company.

Reference: Qpoint Writing (for longer, more polished pieces)

When writing something more structured (closer to the Qpoint blog style), these patterns apply:

  • Scenario-driven openers (drop the reader into a situation)
  • Second person present tense for immersion ("You start with a simple plan")
  • Build the problem through narrative, release with structured lists
  • Rhetorical bookends (end where you started, reframed)

These are tools in the toolbox, not rules. The personal blog defaults to casual first-person.