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` | 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. javascript const greeting = "hello"; 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... yaml version: 2 </details> 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} Then link to them: - [Installation](#installation) - [Usage](#usage) 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. 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. 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. 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. 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 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.