A lo largo de los años hemos intentado tener una documentación en cada proyecto que pueda servir a cualquier miembro del equipo en el momento que lo necesite.
Respecto a la cantidad de documentación, cada proyecto es un mundo pero en general siempre tenemos bastante información que tiene una relación directa con el proyecto.
Hemos probado técnicas, ubicaciones, wikis, documentos y otros sistemas, cada uno con distinto éxito.
A lo largo de los diferentes proyectos hemos comprobado que cuanto más cerca estaba la documentación del código más ventajas teníamos y la información era más valiosa.
Entendemos por cerca, que la documentación este dentro de los mismos ficheros de código, en los mismos directorios o en el mismo repositorio de código.
Estas son algunas de las ventajas que existe cuando la documentación del proyecto esta cerca de los recursos :
-Más fácil tenerla actualizada
Al estar cerca del código es más sencillo actualizarla cuando realizamos un cambio.
-Más fácil tenerla localizada
No hay que preguntar a nadie donde esta el esquema de conexión el gŕafico de recursos o como acceder al wiki para ver tal objeto. Todo el equipo sabe donde está y donde debe estar.
-Organizada en base al proyecto
Los proyectos suelen tener una organización en base a módulos, componentes, áreas, etc. La documentación puede estar organizada de la misma manera, con lo que si te sabes mover por el código sabes moverte por la documentación
-La documentación y el código se apoyan, es bueno verlo con relación
Cuando tienes dudas en el código del proyecto necesitas ver la documentación que pueda estar relacionada. Cuando quieres ver como se aplica algo de la documentación, es bueno tener el código cerca.
-Si viaja el código que viaje la documentación
En ocasiones necesitas llevarte el código a una máquina sin conexión o cambiar de máquina. Si el código va junto a la documentación no tendrás que hacer dos pasos.
-Si tengo acceso al código tengo acceso a la documentación.
Si tienes unos privilegios de acceso al código, normalmente van parejos para el acceso a la documentación
Uno de los ejemplos prácticos de llevar la documentación cerca del código es la documentación de Qt, donde los ex-nokia y ex-trolltech documentaban en el código, su inmensa librería esta perfectamente documentada y actualizada.
Si tu documentación esta dentro del código existen herramientas que te ayudan a extraer esa documentación y compactarla de una forma muy accesible. Doxygen o JavaDoc son claros ejemplos.
En otros casos los IDEs de las plataformas te permiten crear directamente la documentación, en el caso de Velneo puedes crear esquemas directamente desde el vDevelop.
davidgu 