El ciclo de vida ideal de la documentación de un proyecto de ingeniería se parece a esto:
- Un documento de diseño se escribe antes de que se inicie la implementación o al menos antes de que esté demasiado avanzado. Explica los objetivos y no objetivos del sistema y enumera las posibles soluciones y sus respectivas compensaciones. Con suerte informado por los objetivos explícitos, elige una de esas soluciones como el enfoque actual. El documento de diseño se mantiene corto (~ un par de párrafos / conjuntos de viñetas) y de alto nivel para evitar equivocarse y / o exigir mucho tiempo. Aquí hay un ejemplo particularmente completo de Asana: https://docs.google.com/document…
- Durante la implementación, los límites públicos / privados se consideran cuidadosamente, y los comentarios orientados a la implementación se aplican a funciones privadas y los comentarios orientados a casos de uso se aplican a las funciones públicas. Se siguen las mejores prácticas, como la organización razonable del código y la anotación de cualquier parámetro no obvio en los comentarios.
- Como parte de la implementación (o antes si TDD es apropiado), las pruebas documentan el comportamiento en casos de borde / error, así como las API básicas, los casos de uso, etc. Las mejores prácticas de prueba merecen su propio conjunto de puntos pero se aplican principios similares a la documentación, donde los análogos de la documentación incorrecta, la documentación de alto nivel y la documentación de bajo nivel son, respectivamente, pruebas inocentemente fallidas, pruebas funcionales y pruebas unitarias.
- Cuando los sistemas pasan por una actualización significativa, los documentos de diseño se modifican para reflejar las actualizaciones, pero el nivel de detalle sigue siendo bajo.
- Con el tiempo, se agrega gradualmente algún tipo de documentación de alto nivel para describir cómo los sistemas funcionan juntos y cómo moverse por la base de código, pero el nivel de detalle se mantiene incluso más bajo que los documentos de diseño de los sistemas.
- Todo lo anterior se aplica con criterio, y se omite la documentación que es evidente por sí misma, en particular, que consume mucho tiempo, que es difícil de mantener o de cualquier otra forma que no sea rentable.
- Aceptas que no haces nada de lo anterior perfectamente, pero está bien: todo es un equilibrio entre prioridades en competencia, especialmente tu tiempo.
- Un buen momento para agregar documentación es durante la incorporación. Debe enseñar a sus nuevos empleados sobre su sistema, y escribirlo lo ayudará a componer sus pensamientos y evitará que tenga que volver a hacerlo la próxima vez que contrate a alguien.