documentation - sistemas - guia para documentar el desarrollo del proyecto de software

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

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

¿Qué cosas son importantes para documentar? ¿La documentación de código y diseño debería estar principalmente en el código en forma de comentarios? ¿Deberíamos colocar archivos de texto o documentos de Word directamente en el control de fuente junto con el código? ¿Debemos usar un 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 ampliar 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 escribirlos es demasiado complejo o poco amigable para los desarrolladores, y que después de unos años, los nuevos desarrolladores difícilmente pueden encontrar la poca documentación que se escribió.

Estoy interesado en qué enfoques 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.
Utilizamos Visual Studio y Team Foundation Server para el control de origen y la gestión de elementos de trabajo (tareas).
Utilizamos Scrum y el desarrollo guiado por pruebas, y estamos inspirados en el diseño basado en dominios.
El software consiste en una colección de servicios web y dos clientes GUI.
Otros clientes se integrarán con los servicios web en el futuro. La integración será realizada por otros desarrolladores en otros equipos (de modo 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 una gran cantidad de documentos de MS Office sobre aspectos como requisitos, diseño, presentaciones para los interesados, etc. Es difícil mantener todo actualizado.
También tenemos un wiki de SharePoint solo para el equipo de desarrollo, donde documentamos las cosas de manera no estructurada a medida que avanzamos. Los ejemplos incluyen cómo están organizados nuestros scripts de compilación, nuestra política de pruebas, pautas de codificación.
El software es una aplicación interna en una institución financiera bastante grande.
El software es 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 pagarlo).
El cliente tiene pocas pautas sobre cómo se debe documentar este tipo de proyecto.

Dia de dia

Definitivamente utiliza un wiki. Recomiendo TWiki, ya que es una excelente y extensa implementación de un wiki sin ser demasiado complicado de instalar y administrar.

Aquí hay un par de pensamientos iniciales.

Categorías:

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

permitir a las personas agregar nuevas categorías o subcategorías según sea necesario,
Permita que las personas retengan las (sub) categorías según sea necesario y tal vez según lo acordado para esta, de modo que no obtenga la fragmentación de varios nombres para básicamente lo mismo.
Deje que todas las (sub) categorías 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

Comience a usar una nube de etiquetas. Por cierto, aquí hay un excelente complemento disponible para que TWiki comience a clasificar el contenido al principio del proyecto. Actualizar etiquetas es casi imposible de hacer. Comenzar a etiquetar temprano también permite a las personas buscar información que pueda estar allí en lugar de tener la misma información ubicada en múltiples lugares.

HTH volveré y agregaré más puntos cuando los piense.

Lo peor para mí que la falta de documentación es el exceso de 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 corre el riesgo de no leerse nunca .

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

Primero y más importante, haga que los comentarios se escriban de tal manera que NDoc pueda analizarlos. Esta es la mejor manera de documentar el código, 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.

Segundo, lograr que los desarrolladores escriban documentación no es fácil, y hacer 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, a rastrear las entradas y, cuando termines una iteración, generarán notas de la versión.

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

Creo que las cosas más importantes para documentar son las decisiones . Esto va para todo, desde los requisitos hasta las elecciones 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 general que comentar el por qué es mucho mejor que el cómo .

En mi opinión, la forma en que documente estas decisiones no importa mucho, ya sea que use un Wiki o un documento de Requisitos hecho en Word. Lo más importante es que estos documentos están siempre actualizados y que cualquiera puede acceder a ellos fácilmente. Esto se puede lograr usando un wiki o colocando los documentos bajo el control de código fuente, como usted dice. 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 hacer un seguimiento de los cambios, para que sepa qué ha cambiado y por qué. Además, intentamos documentar el código de manera significativa y documentar las principales decisiones de diseño. Intentamos no documentar demasiado, por ejemplo, cosas menores, ya que siempre es difícil mantenerlas actualizadas y no vale la pena el esfuerzo, imho.