random.qmx.me Style Guide

Voice

First person, conversational, unfiltered. Write like you’re explaining something to a friend who gets it. Use “I”, be direct, share opinions. This isn’t academic writing or corporate documentation.

Examples from the blog:

  • “I’ve been enjoying Dream Theater’s last release…”
  • “Thankfully I was really disciplined…”
  • “Sure, it’s clear as crystal that we have a tool problem here.”

Tone

Honest and Direct

Say what you think. If something is hard, say it’s hard. If something sucks, say it sucks (but explain why).

  • “Writing is Hard. Wow.”
  • “osxfs is really, really terrible.”
  • “You won’t see me clicking that awful green button at GitHub’s web ui. NEVER.”

Opinionated but Grounded

Strong opinions are fine - encouraged, even. But back them up with reasoning or experience.

Good: “Technical writers are the bassists of the software world. People don’t give them the due credit…” Not this: Wishy-washy hedging that doesn’t commit to anything

Casual but Competent

Keep it relaxed. Use contractions. Throw in the occasional emoji if it fits. But don’t sacrifice clarity or accuracy for casualness.

Structure

Start Strong

Hook readers immediately. Get to the point. Use the <!--more--> tag after your opening (usually 1-3 paragraphs) to create an excerpt.

Break Things Up

  • Use headings liberally (H2 ##, H3 ###)
  • Short paragraphs - usually 1-4 sentences
  • Lists everywhere - bullet points and numbered lists are your friends
  • Blockquotes for emphasis or external content

End with a Wrap

Common closings:

  • “hope this is useful!”
  • “hope you find this useful :)”
  • “Well, that’s a wrap! Hope this is useful to someone else!”

Simple, unpretentious sign-off.

Formatting

Emphasis

  • Bold for important concepts, tools, key points
  • Italics for subtle emphasis or when introducing terms
  • code formatting for commands, file paths, package names, technical terms

Lists

Use them heavily. They make content scannable and break up walls of text.

Images

Include screenshots, photos, diagrams when they add value. Don’t force it.

Code Blocks

Show actual code when relevant. Keep examples practical.

Language

Be Specific

Concrete details > vague descriptions

Good: “17g of beans, a little bit coarser grind, water at 93ºC” Avoid: “Use the right amount of coffee and hot water”

Short Sentences

Not always, but often. They punch harder. They’re easier to read. Mix in longer ones for rhythm.

Active Voice

Good: “I gave preference to Counterculture’s coffee” Avoid: “Preference was given to Counterculture’s coffee”

Personality

  • Parenthetical asides when appropriate
  • “Sigh”, “Wow”, “Let’s be honest here”
  • Occasional humor
  • Real reactions to real experiences

Content Patterns

Personal Experience

Share what you actually did, used, or tried. This blog is built on real experience, not theoretical knowledge.

  • “Before moving to the US, I’ve passed all my coffee gear to a very dear friend.”
  • “Here I was again scrambling to remember what the heck I did to start with.”

Practical Details

Include the nitty-gritty:

  • Exact tools and versions
  • Commands you run
  • Specific numbers and ratios
  • Links to products/tools/resources
  • Real costs or measurements

Problem → Solution

Many posts follow this flow naturally:

  1. Here’s the problem I encountered
  2. Here’s what I tried
  3. Here’s what worked (or didn’t)
  4. Here’s what I learned

Technical Depth

Vary based on topic, but don’t dumb things down. Readers are technical. Explain what needs explaining, skip obvious stuff.

Front Matter

---
layout: post
title: Clear, Descriptive Title
date: YYYY-MM-DD
tags:
- tag1
- tag2
---

What to Avoid

  • Corporate speak or buzzwords
  • Being wishy-washy - commit to your opinions
  • Walls of text without breaks
  • Leaving out the interesting details
  • Pretending you have all the answers
  • Over-explaining obvious things
  • Being mean without being constructive

The Meta Point

This blog is personal. It’s not trying to be the definitive guide to anything. It’s one person’s experiences, opinions, and learnings. That authenticity is the style.

Write what you’d want to read. Share what you actually learned. Be honest about what worked and what didn’t.