Contenido verificado asociado a este RA
Fundamentos de la Documentación de Aplicaciones Web y Herramientas Generadoras
Esta unidad introduce la importancia de la documentación en el ciclo de vida del desarrollo web, identificando diferentes tipos de documentación y explorando herramientas específicas para la generación automática a partir del código fuente, así como los formatos de salida más comunes.
Herramientas Colaborativas para la Documentación
Esta unidad se centra en la utilización de plataformas y herramientas que facilitan la elaboración y el mantenimiento colaborativo de la documentación, asegurando que múltiples miembros del equipo puedan contribuir y mantenerla actualizada de forma eficiente.
Sistemas de Control de Versiones para Código y Documentación
Esta unidad explora la instalación, configuración y uso de sistemas de control de versiones (VCS), como Git, para gestionar tanto el código fuente de la aplicación como su documentación asociada, garantizando la trazabilidad y la colaboración segura.
Documentación del Sistema de Control de Versiones y Flujos de Trabajo
Esta unidad aborda la importancia de documentar la instalación, configuración y el flujo de trabajo del sistema de control de versiones utilizado, asegurando que todos los miembros del equipo comprendan cómo interactuar con él y mantengan la coherencia en las prácticas de desarrollo.
Conceptos clave
Documentación de códigoGeneradores de documentaciónJavadocPHPDocJSDocOpenAPI/SwaggerFormatos de documentación (HTML, PDF, Markdown)Colaboración en documentaciónWikis empresarialesConfluenceGitLab WikiGoogle DocsGestión de versiones de documentaciónSistema de Control de Versiones (VCS)GitRepositorio local/remotoCommitBranch
Errores que conviene evitar
- Documentación desactualizada: Causa: No se considera parte del desarrollo. Corrección: Automatizar la generación y vincular la actualización a la revisión de código.
- Comentarios de código redundantes: Causa: Explicar lo obvio. Corrección: Comentar 'por qué' y 'qué' de forma concisa, dejando el 'cómo' al código.
- Uso inconsistente de etiquetas: Causa: Falta de estándar o revisión. Corrección: Establecer guías de estilo y usar herramientas de linting para comentarios.
- Documentación en silos: Causa: Cada equipo usa su propia herramienta sin integración. Corrección: Centralizar en una plataforma principal y definir flujos de trabajo.
- Falta de revisión: Causa: Se publica sin control de calidad. Corrección: Implementar procesos de revisión por pares o por un editor de documentación.
- Sobrecarga de información: Causa: Documentar cada detalle sin filtrar. Corrección: Enfocarse en la información esencial y mantenerla concisa.
- Commit de credenciales: Causa: No usar .gitignore o variables de entorno. Corrección: Excluir archivos sensibles y usar gestores de secretos.
- Historial de commits sucio: Causa: Mensajes de commit poco claros o commits muy grandes. Corrección: Realizar commits pequeños y atómicos con mensajes descriptivos.