Documentos para un proyecto?

Question

Trabajo para una empresa certificada de nivel 5 CMMI y una de las cosas que odio es la cantidad de documentos que preparamos (como programador, ya odio los documentos). Tenemos muchos documentos como PID (project initiation doc), Business requirements, System requirements, tech spec, Code review checklist, issue logs, Defect logs, Configuration plan management, Configuration management check list, Release documents y lots ...

Casi el 90% de estos documentos se acaban de hacer por el bien de la auditoría QA :) .. ¿Cuáles cree que son los documentos más importantes para un proyecto? ¿Qué documentos puede usar a largo plazo otro desarrollador?

Por favor comparta sus buenas prácticas aquí. Me gustaría usarlos para mis propios proyectos o la compañía que planeo comenzar a largo plazo.

Gracias

Answer 1

El documento clave es un good functional spec. Debe haber una y sólo una documento de referencia para un sistema.

La documentación de exceso prolifera una gran cantidad de pequeños requisitos y documentos de especificaciones cada vez que alguien cambia un sistema o interfaz. Para un sistema de cualquier complejidad, en poco tiempo tendrás tus especificaciones distribuidas alrededor de varios cientos de archivos word, excel, visio e incluso powerpoint. Cuando esto sucede, pierde claridad acerca de lo que es actual o incluso si ha localizado e identificado toda la documentación pertinente.

La progresión de la especificación BRD-SRD-Tech se basa en la suposición de que la empresa firma el BRD, un analista empresarial firma el SRD contra los requisitos documentados en el BRD y la especificación técnica se firma contra el SRD. Esto genera una red de aprobaciones, documentos múltiples con información redundante y hace que sea difícil y torpe mantener actualizados los documentos de especificaciones.

Debido a esto, la documentación posterior de los requisitos tiende a tomar la forma de una serie de solicitud de cambio y requisitos suplementarios y documentos de especificaciones, cada uno con su propio proceso de aprobación y auditoría. Usted gana CYA y el seguimiento de auditoría (o al menos la apariencia de un seguimiento de auditoría), pero pierde claridad. Ahora no hay un documento de referencia definitivo para el sistema y es difícil establecer lo que es actual o relevante para una actividad en particular. El resultado neto es que el proceso de análisis de su empresa se empantana en la investigación forense, que agrega gastos generales y latencia a los plazos de entrega.

Un documento de especificaciones debe ser construido de tal manera que haya una referencia definitiva para cualquier sistema o subsistema dado. El documento debe mantenerse actualizado y versionado. Obtenga un good technical documentation tool como Framemaker, para que su proceso pueda escalar y el documento tenga cierta integridad estructural del tipo que falta en Word.

Answer 2

Para mí, el único documento real que uso es una especificación. Cuanto más detalles, mejor. Sin embargo, no es necesario que todo esté completo al mismo tiempo, y no es necesario que sea especialmente formal. Lo que es mucho más útil para mí que los documentos que se revisan y firman y se vuelven a verificar, y el doble firmado siempre puede obtener la última versión de un documento. Y poder hablar con la gente sobre lo que han escrito y tomar una decisión en caso de cualquier ambigüedad. esto es mucho más útil para mí que cualquier otra cosa.

En resumen: una especificación es el único documento que he encontrado útil; sin embargo, es insignificante en comparación con tener un administrador de proyectos que conoce el sistema propuesto y puede tomar decisiones sensatas basadas en lo que saben.

Answer 3

¿Cuáles cree que son los documentos más importantes para un proyecto?

Diferentes personas tienen diferentes necesidades: por ejemplo, los documentos que necesita el propietario (por ejemplo, el contrato comercial) no son los mismos que los documentos que necesita control de calidad.

¿Qué documentos puede utilizar a largo plazo otro desarrollador?

OMI el documento más importante (excepto para el código fuente) es la especificación funcional: porque lo que el software es supone hacer (en oposición a, lo que está haciendo) es la única cosa que no necesariamente puede ser de ingeniería inversa. Ver también How does a good developer keep from creating code with a low bus hit factor?

Answer 4

historias de los usuarios, burn down chart, código

Answer 5

Desde el punto de vista del proyecto, los documentos más importantes son las que normalmente incluyen la palabra plan, tales como el Plan de Proyecto, Plan de Gestión de la Configuración, Plan de Calidad , etc.

Lo que está describiendo es común en las mejoras de proceso, y normalmente responde a dos causas principales. Una es que el sistema realmente se está excediendo y obstaculizando el trabajo real que se está haciendo. En realidad, se responde a otra pregunta: no se trata de que los documentos solo se realicen para auditar, y su enfoque no debe ser qué tan útil es el documento para otros desarrolladores, sino para el proyecto o para la empresa en general.

Uno generalmente mira las cosas desde su propia perspectiva, a veces es necesario mirar la imagen general.

Answer 6

La documentación es como el tofu: la mayoría de la gente lo odia hasta que se da cuenta de que, en las condiciones adecuadas, puede ser realmente bueno.

El problema es que lo que usted considera que la documentación se hace principalmente por motivos de documentación. Usted, como desarrollador, no ve ningún valor inmediato en los documentos que produce porque sabe que puede hacer su trabajo sin todos los informes TPS que debe realizar.

Lamentablemente, voy a apostar que no hay mucho que pueda hacer en una empresa donde se lo obliga a comer tofu crudo todo el tiempo. Probablemente solo tendrá que absorberlo y escribir los documentos que su empresa requiera, pero al menos puede hacer una cosa ... puede escribir documentos que al menos son útiles para ,, y puede pasarlos junto con con su código para otros que lo mantendrán.

Además de la documentación en línea, puede configurar una wiki para que la utilice usted y las personas de su equipo. Este tipo de documentación es con capacidad de búsqueda de, que ya es una gran ventaja para los desarrolladores, además es más un documento vivo que un trabajo de tarea que usted tuvo que escribir. Ya publicas en SO, así que solo piensa en tu documentación como unir tus conocimientos en un lugar más útil.

Answer 7

Soy un fan de los viejos 4 + 1 vistas:

• vista de casos de uso (cuentos a/k/a usuario). Hay varias formas: casos de uso adecuados, casos de uso progresivos que no están bien definidos y épicos que deben descomponerse.

• Vista lógica. La vista "estática". Los diagramas de clase UML y similares funcionan bien aquí como documento de diseño. Esto también incluye formatos de solicitud y respuesta para varios protocolos. Aquí es donde documentamos las solicitudes y respuestas RESTful. Esto incluye el diseño REST URI.

• Vista de proceso. La vista "dinámica". Diagramas de actividad UML, diagramas de secuencia y gráficos de estado y similares aquí para documentos de diseño. En algunos casos, las narraciones simples funcionan bien. En otros casos, existe un patrón de diseño State, y requiere una combinación de diagramas de clase y de estado para mostrar cómo interactúan los objetos con estado.

  Esto también incluye protocolos (por ejemplo, REST). Aquí es donde definimos cualquier procesamiento especial para las diversas solicitudes REST.

  Esto también incluye una autenticación o reglas de autorización y cualquier otro aspectos transversales como la seguridad, la explotación forestal, etc.

• Vista de componente. Las piezas que estamos construyendo para el despliegue. Esto incluye las cosas de las que dependemos, la estructura de los módulos y paquetes, etc. Este es a menudo un simple diagrama de componentes o una lista de componentes y sus dependencias.

• Vista de implementación. Intentamos generar esto a partir del código implementado. Como usamos Python, utilizamos epydoc para crear la documentación de la API. También usamos Sphinx para importar documentación de módulos en esta vista del software.

  Esto también incluye los parámetros, configuraciones y detalles de configuración.

Esto, sin embargo, no es suficiente.

Cuando comienzan los proyectos, tiene que trabajar en esto a través de una serie de sprints.

1. Los primeros sprints crean solo la vista de caso de uso.

2. Los sprints subsiguientes crean una "arquitectura" para implementar los casos de uso. El documento de arquitectura tiene 4 + 1 vistas, pero a un alto nivel de abstracción. Resume la estructura de los esquemas modelo, las solicitudes y respuestas, el procesamiento RESTful, otros procesos, los componentes esperados, etc. Nunca tiene una vista de Implementación. En general, hacemos referencia a la guía del operador y a los documentos API como la vista de despliegue de una arquitectura.

3. Luego los sprints de diseño y construcción construyen (y actualizan) documentos detallados de vista 4 + 1 para varios componentes.

4. Luego, los sprints de lanzamiento crean (y actualizan) las vistas de implementación.