Effective Documentation with Markdown and Git
Documentation is the unsung hero of software projects. Good documentation reduces onboarding time, prevents recurring questions, and ensures that knowledge survives team changes. Treating documentation as code — writing it in Markdown, storing it in Git, and building it with CI — ensures it stays versioned, reviewed, and up to date. This article covers the docs-as-code workflow using MkDocs and Material for MkDocs, along with strategies for keeping documentation fresh.
Markdown for Documentation
Markdown is the lingua franca of documentation. It is plain text that is readable in any editor and renders to clean HTML. Most documentation generators (MkDocs, Hugo, Docusaurus, Jekyll) support GitHub-Flavored Markdown with extensions for tables, code blocks with syntax highlighting, task lists, admonitions (notes, warnings, tips), and mathematical formulas via LaTeX. Keep paragraphs short, use descriptive headings (every heading level creates a navigation entry), and include code examples for every API function or configuration step. A documentation page should answer three questions: what does this do, why would I use it, and how do I use it? Start each page with a brief summary of what the page covers and who it is for.
# mkdocs.yml - Project configuration
site_name: My API Documentation
site_description: Developer docs for the MyAPI service
theme:
name: material
features:
- navigation.tabs
- navigation.sections
- navigation.expand
- content.code.copy
- content.code.annotate
palette:
- scheme: default
primary: indigo
accent: indigo
nav:
- Home: index.md
- Getting Started:
- Installation: guides/installation.md
- Quickstart: guides/quickstart.md
- API Reference:
- Authentication: api/auth.md
- Users: api/users.md
- Orders: api/orders.md
- Guides:
- Deployment: guides/deployment.md
- Troubleshooting: guides/troubleshooting.md
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.tabbed
- pymdownx.highlightOrganizing Your Documentation with Diátaxis
The Diátaxis framework divides documentation into four types, each serving a different user need. Tutorials are learning-oriented — step-by-step guides that take a beginner from zero to a working result, with no assumptions about prior knowledge. These should be the first thing a new user encounters. How-to guides are task-oriented — recipes for solving specific problems (how to deploy, how to reset a password, how to configure caching). Users reach for these when they have a specific goal. Reference docs are information-oriented — exhaustive descriptions of APIs, configuration options, and command-line flags. These should ideally be generated from code to stay in sync. Explanation is understanding-oriented — conceptual background, design decisions, architecture overviews, and comparisons with alternatives. A healthy documentation site has content in all four categories with clear navigation.
Automated Documentation Builds
Set up a CI pipeline that rebuilds the documentation site on every push to the main branch. MkDocs produces a static HTML site that can be deployed to GitHub Pages, GitLab Pages, Netlify, or any web server. For GitHub Pages, use mkdocs gh-deploy --force which builds the site and pushes it to the gh-pages branch. Add a pre-commit hook to check for broken links and validate Markdown syntax. For API documentation generated from code (like OpenAPI specs), integrate the spec generation into the build so the docs always match the current code.
# Build and preview locally
mkdocs build
mkdocs serve # visit http://localhost:8000
# Deploy to GitHub Pages
mkdocs gh-deploy --force
# GitHub Actions workflow for automated docs
name: Build and Deploy Docs
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: pip install mkdocs-material
- run: mkdocs build
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./siteKeeping Documentation Fresh
Outdated documentation is worse than no documentation — it actively misleads users and erodes trust. Set up automated checks in CI that test code examples from documentation (using doctest or a custom script that extracts and runs code blocks in isolation). Track documentation updates as part of your definition of done for each feature: no feature is complete until its documentation is updated. Assign a documentation rotation on your team where someone spends 10% of their time reviewing and updating docs each sprint. Add a simple feedback mechanism — a “Was this page helpful? Yes/No” widget at the bottom of each page — to identify pages that need attention. When a page gets consistent negative feedback, prioritize it for rewriting. Track documentation debt alongside technical debt in your issue tracker so it gets the attention it deserves.
Writing Style and Conventions
Use active voice and direct address (“You can configure the API by editing the config file” not “The API can be configured”). Write in present tense. Use consistent terminology throughout — if you call it a “workspace” in one place, do not call it a “project” in another. Include one concept per paragraph. Use bullet points for lists of items and numbered steps for procedures. Keep code examples concise and focused on the point being illustrated — do not include irrelevant boilerplate. Every code example should have a comment or surrounding text showing the expected output. Use screenshots and diagrams sparingly but deliberately — a well-placed architecture diagram communicates in seconds what text takes paragraphs to explain.
