Write Docs People Actually Enjoy Reading
Markdown is everywhere: READMEs, wikis, API docs, even internal memos. But most of what I see is plain and underused. After years of writing and maintaining docs, I’ve collected a few tricks that make them far more readable and maintainable.
Use Tables for Comparison, Not Layout
Tables are great for structured data, but people misuse them for layout. Keep them for actual comparisons: options, versions, parameters.
| Option | Description | Default |
|--------|-------------|---------|
| `--verbose` | Show extra output | `false` |
| `--level` | Log level (debug/info/warn) | `info` |
Enter fullscreen mode Exit fullscreen mode
That renders cleanly and is easy to scan. Don’t use tables to force a two-column layout; that’s what HTML is for, and it’s not worth the pain.
Fenced Code Blocks with Language Tags
Always specify the language. It gives syntax highlighting and helps screen readers.
Enter fullscreen mode Exit fullscreen mode
javascript
const greeting = “hello”;
Enter fullscreen mode Exit fullscreen mode
markdown
Use text for plain output, bash for shell commands, and diff for changes. It’s a small habit that pays off.
Collapsible Sections for Optional Content
Long docs bury the core. Wrap optional details in collapsible sections (works on GitHub and many platforms).
<details>
<summary>Advanced configuration</summary>
Here's the deep dive...
Enter fullscreen mode Exit fullscreen mode
yaml
version: 2
</details>
Enter fullscreen mode Exit fullscreen mode
yaml
Readers can skip it without scrolling past a wall of text.
Anchor Links for Navigation
Long docs need a table of contents. Markdown auto-generates anchors from headings, but they can be unpredictable. Set explicit IDs to be safe.
## Installation {#installation}
## Usage {#usage}
Enter fullscreen mode Exit fullscreen mode
Then link to them:
- [Installation](#installation)
- [Usage](#usage)
Enter fullscreen mode Exit fullscreen mode
This works on GitHub, GitLab, and most static site generators.
Blockquotes for Callouts
Use blockquotes to highlight warnings, tips, and notes. They stand out visually without breaking flow.
> **Warning:** Do not run this in production.
> **Tip:** Use `--dry-run` first.
Enter fullscreen mode Exit fullscreen mode
Some renderers support custom labels like > [!NOTE] (GitHub), but plain bold text works everywhere.
Escape the Underscore Problem
When writing about code, underscores can trigger italics. If you’re writing a filename like my_file.rb, wrap it in backticks or escape the underscores.
Use `my_file.rb` or my\_file\_.rb.
Enter fullscreen mode Exit fullscreen mode
Backticks are cleaner.
Use Definition Lists (When Supported)
Some Markdown flavors (like Pandoc) support definition lists. They’re perfect for glossaries or explaining terms.
Term
: Definition of the term.
Another term
: Definition of the other term.
Enter fullscreen mode Exit fullscreen mode
If your platform doesn’t support them, fall back to a table or bold text.
Keep Line Length Reasonable
Hard-wrap lines at 80-100 characters. It makes diffs cleaner and editing easier. Most editors can do this automatically.
This is a long paragraph that is hard to read in source form. If you
wrap it at 80 characters, it's easier to review changes.
Enter fullscreen mode Exit fullscreen mode
Comments for Maintainers
Use HTML comments to leave notes for future editors that won’t show in the rendered output.
<!-- TODO: Update this section after v2 release -->
## Compatibility
Enter fullscreen mode Exit fullscreen mode
This is invaluable for team docs.
Final Thought
Markdown is simple, but a few deliberate choices make a huge difference. Pick the tricks that fit your platform and stick with them. Your future self and your readers will thank you.