Skip to the content ForoHackers
Log inJoin

Documentation: start here

Documentation
#2887 · · Quote · Report

Documentation is the written knowledge that lets people use, operate and change software without asking its authors. It includes guides, API references, design notes, runbooks and comments. Docs rot when nobody owns them, so the best teams treat them like code: versioned, reviewed and tested.

Key concepts

  • Four kinds of need: tutorials teach, how-to guides solve a task, references list facts, explanations give background.
  • Docs as code: plain text in version control, reviewed in the same change as the code it describes.
  • Findability: a good structure, search and links matter as much as the prose.
  • Freshness: dates, owners and automated checks, such as running the examples, stop silent decay.
  • Code comments: explain why, not what; the code already says what.

Vocabulary

  • README: the first file a reader sees, saying what the project is and how to start.
  • Runbook: step-by-step instructions for operating or recovering a system.
  • Changelog: a human-readable list of changes between versions.
  • Docstring: documentation written inside the source, next to a function or type.

What to study, in order

  1. Write a README that lets a stranger install and run your project in ten minutes.
  2. Keep your docs in the repository and review them in the same pull request as code.
  3. Generate an API reference from docstrings, then add the hand-written guide it needs.
  4. Write a runbook for one failure and have someone else follow it.
  5. Test the examples automatically so they cannot drift from the code.

Related tags

#technical-writing #api-design #version-control #open-source

You are not logged in, so this goes up anonymously: no account, no name and no address is stored with it, and it may carry no link and no image. Log in or join to post under your name. Our web server's logs keep the address and time of every request for up to 14 days; to keep yours out of them, use Tor. To reach the staff in confidence, use the drop. Sign as a returning source (a key kept only in this browser)

Sending takes a few seconds here: your browser first works out a proof of work against spam.

Reply