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
- Escribe un README con el que un desconocido instale y ejecute tu proyecto en diez minutos.
- Guarda tus documentos en el repositorio y revísalos en el mismo pull request que el código.
- Genera una referencia de API a partir de los docstrings y añade la guía escrita a mano que le hace falta.
- Escribe un runbook para un fallo y pide a otra persona que lo siga.
- 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