Skip to the content ForoHackers
Log inJoin

Documentación: por dónde empezar

Documentation
#2888 · · Quote · Report

La documentación es el conocimiento escrito que permite usar, operar y modificar software sin preguntar a sus autores. Incluye guías, referencias de API, notas de diseño, manuales de operación y comentarios. La documentación se pudre cuando nadie se encarga de ella, así que los mejores equipos la tratan como código: con versiones, revisada y probada.

Conceptos clave

  • Cuatro tipos de necesidad: los tutoriales enseñan, las guías prácticas resuelven una tarea, las referencias enumeran datos, las explicaciones dan contexto.
  • Documentos como código: texto plano en control de versiones, revisado en el mismo cambio que el código que describe.
  • Facilidad para encontrar: una buena estructura, la búsqueda y los enlaces importan tanto como la prosa.
  • Frescura: fechas, responsables y comprobaciones automáticas, como ejecutar los ejemplos, frenan el deterioro silencioso.
  • Comentarios en el código: explican el porqué, no el qué; el código ya dice qué hace.

Vocabulario

  • README: el primer archivo que ve el lector, que dice qué es el proyecto y cómo empezar.
  • Runbook: instrucciones paso a paso para operar o recuperar un sistema.
  • Changelog: una lista legible de los cambios entre versiones.
  • Docstring: documentación escrita dentro del código fuente, junto a una función o un tipo.

Qué estudiar, en orden

  1. Escribe un README con el que un desconocido instale y ejecute tu proyecto en diez minutos.
  2. Guarda tus documentos en el repositorio y revísalos en el mismo pull request que el código.
  3. Genera una referencia de API a partir de los docstrings y añade la guía escrita a mano que le hace falta.
  4. Escribe un runbook para un fallo y pide a otra persona que lo siga.
  5. Prueba los ejemplos de forma automática para que no se separen del código.

Etiquetas relacionadas

#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