Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 39 ยท Markdown and Documentation

Documentation with Markdown

Learn how to write and maintain project documentation in Markdown - README structure, changelogs, architecture decision records, docs as code, link checking and documentation linting - with runnable checks.

Markdown won the documentation world because it is easy to write, easy to review in a pull request, and portable to many outputs. Good documentation is more than syntax, though: it needs structure that readers can navigate, maintenance so it does not rot, and checks so mistakes are caught automatically. This lesson covers the files every project should have, the "docs as code" workflow, and small automated checks you can write yourself. For syntax see Markdown Syntax: The Complete Guide.

The README

The README is the front door of a project. A reader should learn in a minute what it is, whether it is for them, and how to start. A reliable structure:

  1. Title and one-sentence description. What problem does it solve?
  2. Badges or status (optional): build, version, licence.
  3. Quick start. The shortest path to a working result: install and run, with a copy-pasteable code block.
  4. Usage. Two or three common examples.
  5. Configuration. Options, environment variables, config file format.
  6. Contributing. How to set up a dev environment and run tests.
  7. Licence.

Put the most important content first, keep code blocks runnable, and link to deeper docs instead of making the README a book.

Changelogs

A changelog lists notable changes per release, for people rather than machines. The popular "Keep a Changelog" convention uses one section per version, newest first, with ISO dates and fixed categories:

MARKDOWN
## [Unreleased]

## [1.2.0] - 2025-03-14
### Added
- Export to CSV.
### Changed
- Faster startup.
### Fixed
- Crash on empty input.

Categories are Added, Changed, Deprecated, Removed, Fixed and Security. Pair it with semantic versioning (MAJOR.MINOR.PATCH): breaking change, new feature, bug fix. A changelog is not a dump of commit messages; group and explain changes in the reader's words.

Architecture decision records

An ADR is a short Markdown file recording one decision: the context, the choice, and the consequences. They live in the repository (docs/adr/0007-use-postgres.md) so a new teammate can learn why the system looks the way it does. A common template has the sections Title, Status (proposed, accepted, superseded), Context, Decision and Consequences. They are cheap to write and priceless a year later.

Docs as code

"Docs as code" means treating documentation like source code:

  • Store it in the repository, next to the code it describes, in Markdown.
  • Change it in the same pull request as the code, and have it reviewed.
  • Build it in CI with a static-site generator (MkDocs, Docusaurus, Hugo, Astro, mdBook, Sphinx with MyST) and publish automatically.
  • Test it: lint the Markdown, check links, run the code examples, validate front matter.
flowchart LR
  A["Edit .md in a branch"] --> B["Pull request + review"]
  B --> C["CI: lint, check links, run examples"]
  C --> D["Build static site"]
  D --> E["Publish"]

Documentation moves through the same pipeline as code.

Writing tips that help readers

  • Task-first headings ("Connect to a database") beat noun-only ones ("Database").
  • Use short paragraphs, lists and tables for scanning; keep one idea per paragraph.
  • Give every code block a language and make it complete enough to run.
  • Show the expected output next to commands.
  • Prefer relative links between docs pages so links survive a move and work offline.
  • Use consistent terms: do not call the same thing "project", "workspace" and "repo".
  • Mark warnings clearly (blockquote or admonition) and keep them rare.

Automated checks you can write

Documentation breaks quietly: a renamed file leaves dead links, a renamed heading breaks an anchor, a section gets deleted. A tiny script run in CI prevents most of it. The examples below work on documents held in memory; a real version would read files from disk with node:fs.

Node.js A link and anchor checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The checker found the missing page and the stale anchor, and accepted the good links, the external URL and the same-page anchor.

Node.js README and changelog linting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In a real project, wrap such scripts in a CI step and add dedicated tools: a Markdown linter (markdownlint), a spell checker, an external link checker, and a runner that executes the code blocks in the docs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What belongs near the top of a README?

    Readers decide within a minute, so lead with purpose and the fastest way to try the project.
  2. 2. What is an architecture decision record?

    ADRs capture why a choice was made, so future readers do not have to guess.
  3. 3. What does docs as code mean?

    Docs get the same workflow as source: version control, review, automated checks and publishing.
  4. 4. Which check catches a renamed heading?

    Links with #fragment targets break silently when a heading changes, so a link checker should verify anchors.

Summary

  • A good README leads with purpose and a quick start; deeper material gets its own pages.
  • Keep a changelog per release with fixed categories and ISO dates; record decisions in ADRs.
  • Treat documentation like code: version it, review it, build and test it in CI.
  • Automate link, anchor, front-matter and structure checks; they are cheap to write.
  • Write task-first headings, consistent terms and runnable examples.

Next: Writing a Tokenizer and Parser