Saltar al contenido ForoHackers

Documentation: start here

Documentación
#2887 · · Citar · Denunciar

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

No has iniciado sesión, así que esto se publica como anónimo: no se guarda con ello ninguna cuenta, nombre ni dirección, y no puede llevar enlaces ni imágenes. Inicia sesión o únete para publicar con tu nombre. Los registros de nuestro servidor web guardan la dirección y la hora de cada petición hasta 14 días; para que la tuya no quede en ellos, usa Tor. Para escribir al equipo de forma confidencial, usa el buzón. Firmar como fuente habitual (una clave guardada solo en este navegador)

Enviar tarda unos segundos aquí: tu navegador resuelve antes una prueba de trabajo contra el spam.

Responder