Markdown Is the Only Sane Format for Technical Notes

In 2004, John Gruber published the original Markdown spec with a single guiding principle: text should be readable as-is, without looking like it’s been tagged up with HTML. Two decades later, the format has become the lingua franca of technical writing. There’s a good reason for that.

What Markdown Gets Right

Markdown occupies an almost perfect middle ground for technical writers. It’s expressive enough for structured documentation, but constrained enough that you’re never fighting the format. Unlike Word or Google Docs, there’s no invisible state — what you write is exactly what gets rendered.

This matters enormously when you’re moving fast. When you’re in the middle of a debugging session and you need to capture something quickly, the last thing you want is to be thinking about formatting. Markdown gets out of the way.

# Good note-taking session
$ notesploy new incident/api-timeout-2026-02-24

> ## Root Cause
> TCP keepalive not configured on the load balancer.
>
> ## Fix
> Set `net.ipv4.tcp_keepalive_time=60` on all backend nodes.
> Deployed in hotfix/api-keepalive — PR #1892

That note is readable, structured, and portable. You could open it in any editor, cat it in the terminal, or render it in a browser. It will look exactly as intended in all three contexts.

Code Blocks Are First-Class Citizens

For developers, the killer feature of Markdown is fenced code blocks with syntax highlighting. Being able to write:

```python
def exponential_backoff(attempt: int, base: float = 2.0, cap: float = 60.0) -> float:
    return min(base ** attempt, cap)
```

And have it render with proper Python highlighting is not a luxury — it’s the baseline expectation for any tool that wants to serve technical users.

Portability and Longevity

Perhaps the most underrated property of Markdown is its longevity. A .md file written in 2004 is fully readable today with no migration, no format changes, no subscription required. Compare this to proprietary formats that have trapped user data in incompatible versions for decades.

When you write technical notes in Markdown, you’re writing in a format that will outlast every tool you’ll ever use. The notes you write today will be readable by any editor, any renderer, and any developer on any platform without friction.

The Right Level of Structure

One common objection to Markdown is that it’s “too plain” for serious documentation. This is a misunderstanding of what documentation actually requires. Good technical docs need:

• Clear heading hierarchy
• Code blocks with syntax highlighting
• Tables for structured data
• Inline code for commands, variables, and functions
• Links to related resources

Markdown supports all of these with zero additional tooling. And critically, it supports nothing more. The constraint is a feature. When you can’t add an embedded video or a drag-and-drop kanban board to a note file, you write better notes.

Write in Markdown. Your future self will be grateful.