project-management - integrador - certificación pmp
Documentos para un proyecto? (7)
Historias de usuario, diagrama de burndown, código
Trabajo para una empresa certificada CMMI nivel 5 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 de control de calidad :). ¿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
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 la documentación se hace principalmente para la 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.
Desafortunadamente, voy a apostar a que no hay mucho que puedas hacer en una compañía donde te obligan 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 le son útiles, y puede pasarlos junto 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 se puede buscar , lo que ya es una gran ventaja para los desarrolladores, además es más un documento vivo que un trabajo de tarea que debías escribir. Ya publicas en SO, así que solo piensa en tu documentación como unir tus conocimientos en un lugar más útil.
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.
Para resumir: una especificación es el único documento que he encontrado útil, sin embargo, es insignificante en comparación con tener un gerente de proyecto que conoce el sistema propuesto al revés y puede tomar decisiones sensatas basadas en lo que saben.
Soy fanático de las viejas 4 + 1 vistas:
Usar vista de caso (historias de usuario de a / k / a). 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, hay un patrón de diseño de estado y requiere una combinación de diagramas de clases y gráficos 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 aspecto transversal como seguridad, registro, etc.
Vista de componentes 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 los proyectos comienzan, tienes que trabajar en esto a través de una serie de sprints.
Los primeros sprints compilan solo la vista de caso de uso.
Los sprints posteriores 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.
Luego, los sprints de diseño y construcción construyen (y actualizan) documentos de vista 4 + 1 detallados para varios componentes.
Luego, los sprints de lanzamiento crean (y actualizan) las vistas de implementación.
Desde el punto de vista del proyecto, los documentos más importantes son aquellos que normalmente incluyen la palabra Plan, como el Plan del proyecto, el Plan de gestión de la configuración, el Plan de calidad, etc.
Lo que está describiendo es común en las mejoras del 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 realizar auditorías, y su enfoque no debe ser qué tan útil es el documento para otros desarrolladores, sino para el proyecto o la empresa en su conjunto.
Uno generalmente mira las cosas desde su propia perspectiva, a veces es necesario mirar la imagen general.
¿Cuáles crees que son los documentos más importantes para un proyecto?
Diferentes personas tienen necesidades diferentes: por ejemplo, los documentos que el propietario necesita (por ejemplo, el contrato comercial) no son los mismos que los documentos que necesita el control de calidad.
¿Qué documentos puede usar a largo plazo otro desarrollador?
IMO, el documento más importante (excepto el código fuente) es la especificación funcional: porque lo que se supone que el software debe hacer (a diferencia de lo que está haciendo) es lo único que no puede necesariamente ser ingeniería inversa. Ver también ¿Cómo evita que un buen desarrollador cree código con un bajo factor de golpe de bus?
El documento clave es una buena especificación funcional. Debe haber un solo documento de referencia para un sistema.
La documentación exagerada 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 comercial 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. Obtiene 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 una buena herramienta de documentación técnica como Framemaker, para que su proceso pueda escalar, y el documento tenga cierta integridad estructural del tipo que falta en Word.