Saltar al contenido ForoHackers

Documentación: por dónde empezar

Documentación
#382 · Ophuscado · · Denunciar

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

Inicia sesión o únete para responder.