Documentación Eficiente en el Flujo de Desarrollo Moderno

¿Por qué es crucial la documentación en el flujo moderno?

La documentación a menudo es un elemento subestimado en el desarrollo de software debido a limitaciones de tiempo y una percepción errónea de su relevancia. Desafortunadamente, el 80% de los desarrolladores no recurre a la documentación interna para resolver sus dudas. Sin embargo, en un flujo moderno eficiente, la documentación cobra vital importancia. Un dato revelador es que el 75% del tiempo de un desarrollador en un proyecto nuevo se dedica a entender el código, lo cual es mucho más difícil sin documentación. Pero, ¿cómo podemos garantizar que la documentación sea efectiva y útil?

• Ubicación estratégica: Debe encontrarse integrada con el código, de modo que esté disponible en el momento preciso y sin necesidad de buscarla en otro lugar.
• Conexión y accesibilidad: Al estar conectada directamente al entorno de trabajo, es accesible y puede crecer de manera iterativa conforme surgen nuevas preguntas sobre un bloque de código.
• Exportabilidad: Se pueden crear textos bien organizados, como en procesos de inducción para nuevos desarrolladores, maximizando su utilidad más allá del código en sí.

¿Cómo mejorar la captura y organización del conocimiento en la documentación?

El uso de herramientas modernas como CodeChat no solo ayuda a mantener el enlace entre conversaciones y código, sino que automatiza la captura de conocimiento. Esto elimina el esfuerzo manual de decidir qué vale la pena documentar. La solución está en capturar todas las tareas relacionadas con el código y filtrar información útil de lo que es desechable.

¿Qué elementos deben capturarse?

• Comentarios y mensajes.
• Incidencias y errores en producción.
• Sugerencias y diagramas.

Todos estos elementos y sus metadatos se recolectan y organizan automáticamente cerca del código. Al igual que los cambios se documentan en Git para mantener el historial, esta metodología persigue que entendamos el "por qué" de las modificaciones.

¿Dónde debe almacenarse esta información?

Idealmente, con el código mismo, garantizando que el acceso sea directo, útil y conectado. Este sistema interactivo permite que la documentación crezca conforme aparecen nuevas consultas.

¿Cómo facilitan los codemarks el acceso y gestión de la documentación dentro del código?

Los codemarks son una herramienta clave que conecta el código con comentarios o issues, proporcionando una serie de funcionalidades valiosas para cualquier equipo de desarrollo:

• Compartir y seguir discusiones: Similar a redes sociales como Twitter, permiten el seguimiento de conversaciones relevantes, notificando actualizaciones.
• Enlace y archivos contextuales: Copiar enlaces a otros sistemas de documentación y archivar codemarks cuando dejan de ser útiles.
• Inyección en el código: Codemarks se pueden inyectar directamente, y adaptarse a la evolución del código.
• Relación entre diferentes bloques de código: Un codemark puede referirse a múltiples bloques, mejorando la coherencia de la documentación.

¿Qué papel juegan los tags?

Los tags permiten etiquetar partes del código, creando asociaciones entre ellas y facilitando el salto entre áreas relacionadas. Son útiles en procesos como la inducción de nuevos desarrolladores, permitiendo organizar la documentación de manera efectiva.

¿Cómo apoyar un fluido moderno mediante herramientas de integración?

El flujo moderno se trata de integrar herramientas constantes en el propio editor, optimizando tiempo y calidad del código. Herramientas como GitHub, Jira y Slack, cuando se integran efectivamente mediante soluciones como Codestream, pueden:

• Reducir esfuerzos al mantener todo en un solo lugar (editor preferido como Visual Studio Code).
• Fomentar una colaboración flexible a través de feedback requests y codechat, minimizando barreras en la comunicación.
• Mejorar la eficiencia organizacional al aumentar la transparencia y documentar el conocimiento generado en tiempo real.

La implementación comienza de manera individual, luego se expande al equipo y eventualmente toda la organización se beneficia de este enfoque unificado y eficiente.