Markdown Best Practices for Software Documentation

Good documentation is as important as good code. Markdown has become the standard format for technical documentation across GitHub, GitLab, Confluence, and countless other platforms. Here are the patterns that top engineering teams use.

Structure Your Documents

Every document should have a clear hierarchy. Use a single # H1 for the title, then ## H2 for major sections, ### H3 for subsections.

# API Reference

## Authentication

### API Keys

### OAuth 2.0

Never skip heading levels — going from ## to #### confuses both readers and screen readers.

Code Blocks Are Non-Negotiable

Always specify the language for code blocks. This enables syntax highlighting and signals to readers what they're looking at:

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

For terminal commands, use bash or sh. For configuration files, use the appropriate format (yaml, toml, json).

Document Command Outputs

When documenting CLI tools, show both the command AND its expected output:

```bash
$ git status
On branch main
nothing to commit, working tree clean
```

Use Tables for Configuration Options

Tables are perfect for documenting configuration parameters:

Callouts for Important Information

Many platforms support callout/admonition syntax. Use blockquotes as a fallback:

> **Note:** This feature requires Node.js 18 or later.

> **Warning:** This operation is irreversible.

Keep It Maintainable

• Use relative links for internal documentation references
• Keep image files in a dedicated docs/images/ directory
• Include a "Last Updated" date in long-lived documents
• Break very long documents into smaller linked files

Version Your Docs with Your Code

Documentation lives in the same repository as the code it describes. This ensures docs stay synchronized with releases and can be reviewed in the same pull request as code changes.