¿Cuáles son las formas buenas y malas de documentar un proyecto de software?

Question

Soy responsable de encontrar una buena manera de documentar el proyecto de software en el que estoy trabajando.

¿Qué elementos son importantes para documentar? ¿La documentación del código y el diseño debe estar principalmente en el código en forma de comentarios? ¿Deberíamos poner archivos de texto o documentos de Word directamente en el control de origen junto con el código? ¿Deberíamos usar una wiki?

Los factores a considerar incluyen qué tan fácil es para el equipo actual crear la documentación, y qué tan fácil es para otros desarrolladores encontrar, corregir y extender la documentación más adelante. Mi experiencia en muchos proyectos es que los desarrolladores tienden a no escribir documentación porque el sistema para escribirlo es demasiado complejo o desagradable para el desarrollador, y que después de algunos años, los nuevos desarrolladores difícilmente pueden encontrar la poca documentación que se escribió.

Me interesan los enfoques que ha utilizado en proyectos similares. ¿Qué funcionó bien, qué no funcionó bien y por qué?

Algunos datos clave sobre el proyecto:

• La plataforma es C# y .NET.
• Usamos Visual Studio y Team Foundation Server para el control de código fuente y la gestión de elementos de trabajo (tareas).
• Utilizamos Scrum y el desarrollo basado en pruebas y estamos inspirados en el diseño impulsado por el dominio.
• El software consiste en una colección de servicios web y dos clientes GUI.
• Otros clientes se van a integrar con los servicios web en el futuro. La integración será realizada por otros desarrolladores en otros equipos (por lo que los servicios web forman un tipo de API).
• SharePoint es muy utilizado en todo el entorno de desarrollo. La mayoría de los proyectos tienen un sitio de SharePoint, incluido el nuestro.
• En el sitio de SharePoint de nuestro proyecto, actualmente tenemos muchos documentos de MS Office sobre requisitos, diseño, presentaciones para partes interesadas, etc. Mantener todo actualizado es difícil.
• También tenemos una wiki de SharePoint para el equipo de desarrollo solamente, donde documentamos las cosas de manera no estructurada a medida que avanzamos. Los ejemplos incluyen cómo se organizan nuestros scripts de construcción, nuestra política de prueba, pautas de codificación.
• El software es una aplicación interna en una institución financiera bastante grande.
• El software está desarrollado por un equipo de seis personas durante un período de ~ 1 año.
• Los desarrolladores son consultores contratados solo para este proyecto, y no estarán disponibles para ayudar en el futuro (a menos que el cliente decida pagar por ello).
• El cliente tiene pocas pautas sobre cómo este tipo de proyecto debe documentarse.

Answer 1

Lo primero y más importante es que los comentarios se escriban de tal forma que NDoc pueda analizarlos. Esta es la mejor manera de documentar el código en sí, ya que los desarrolladores tienen que cambiar muy poco sus prácticas de desarrollo, y puede generar páginas que expliquen el código sin tener que mirar el código.

En segundo lugar, hacer que los desarrolladores escriban documentación no es fácil, y conseguir que lo hagan podría ser un ejercicio inútil. Aquí es donde entran en juego productos como Fogbugz. Ayudarán a administrar el desarrollo con tickets, ayudarán a rastrear los check ins, y cuando haya realizado una iteración, generará notas de la versión.

En conclusión, su mejor opción es encontrar la solución más efectiva que se adapte al proceso existente de los desarrolladores. Si impacta muy poco en su proceso de desarrollo, será más probable que adopten el sistema.

Answer 2

G'day,

Definitivamente use una wiki. Recomiendo TWiki ya que es una implementación excelente y extensa de una wiki sin ser demasiado complicada de instalar y administrar.

Aquí hay un par de ideas iniciales.

Categorías:

empezar con una ontología inicial de lo que desea capturar, pero

• permiten a la gente a añadir nuevas categorías o subcategorías según sea necesario,
• permiten a las personas retitular (sub-) categorías según sea necesario y tal como se acordó para éste, para que no obtenga la fragmentación de varios nombres básicamente por lo mismo.
• deje que las categorías (sub) iniciales se marchiten y mueran si se dejan vacías. Haga esto al final del proyecto ya que algunas áreas solo pueden tener entradas hacia el final de un proyecto.

Etiquetado:

empiece a usar una nube de etiquetas. Por cierto, aquí hay un excelente complemento disponible para que TWiki comience a clasificar el contenido desde el principio del proyecto. Volver a adaptar las etiquetas es casi imposible de hacer. Comenzar a etiquetar temprano también permite a las personas buscar información que ya puede estar allí en lugar de tener la misma información ubicada en varios lugares.

HTH Volveré y añadiré más puntos a medida que los vea.

Answer 3

Lo peor para mí que la falta de documentación es exceso de la documentación.

Tenga en cuenta que sí: es muy importante documentar su proyecto, pero también que la mayor parte de su documentación siempre está en riesgo de nunca haber sido leído.

Por lo tanto, creo que un buen punto de partida consiste en pensar que su documentación es más como algo que puede utilizar para presentar nuevos desarrolladores a su proyecto que una descripción más detallada del funcionamiento interno de su software.

Answer 4

Creo que las cosas más importantes para documentar son las decisiones . Esto va para todo, desde requisitos hasta opciones arquitectónicas. ¿Cuáles son los requisitos del módulo X? ¿Cómo se representan estos requisitos en la arquitectura? ¿Por qué elegiste el patrón arquitectónico A sobre B? ¿Cuales son los beneficios? Lo mismo ocurre con el código fuente: es de conocimiento común que al comentar el por qué es mucho mejor que cómo.

Cómo documentas estas decisiones no importa mucho en mi opinión, ya sea que uses un Wiki o un documento de Requisitos hecho en Word. Lo más importante es que estos documentos están siempre actualizados y que es fácil para cualquiera acceder a ellos.Esto se puede lograr usando una wiki o colocando los documentos bajo el control de la fuente, como dices. Si solo unos pocos tienen acceso a ellos, es más probable que no se actualicen, que no se lean cuando sea necesario.

Utilizamos un Wiki para nuestro proyecto actual y funciona muy bien. Es fácil de acceder para cualquier persona (desarrolladores, gerentes y clientes) y un historial puede realizar un seguimiento de los cambios, para que sepa qué se ha cambiado y por qué. Además, intentamos documentar el código de una manera significativa y documentar las principales decisiones de diseño. Intentamos no documentar demasiado, p. cosas menores, ya que siempre es difícil mantener esas cosas al día y no vale la pena el esfuerzo, yo también.