¿Cuál es la forma correcta de crear documentos de requisitos?

En este momento, mi supervisor está creando documentación de requisitos / especificaciones para mí utilizando el software de seguimiento de errores. Esto me parece una idea terrible, todos los requisitos están en estos pequeños tickets y tengo que hacer clic en este tonto formulario web para obtener los requisitos. ¿Qué es una solución de software sensata para requisitos / especificaciones de software?

Para ser claros, estoy construyendo este gran componente de software con bastantes características y estas características se están estableciendo en este software de seguimiento de errores.

Estoy bastante sorprendido de que hasta ahora nadie haya recomendado el uso de una wiki para los requisitos de seguimiento.

He encontrado que es un sistema casi perfecto, porque:

• Permite a las personas colaborar en los requisitos y hace que este aspecto sea muy visible;
• Le permite mantener actualizados los requisitos fácilmente a medida que avanza el proyecto;
• Puede ingresar y ver el historial en cualquier momento, en caso de una disputa "eso no es lo que acordamos";
• La mayoría de los wikis modernos tienen capacidades de formato decentes, por lo que se ve casi tan bien como un documento de Word;
• Puede hacer un hipervínculo directamente desde sus requisitos a la documentación real;
• Nunca tendrá que preocuparse de que las personas trabajen con copias diferentes / obsoletas;
• Los requisitos pueden comenzar a tratarse como un proceso iterativo, al igual que el diseño / implementación;
• Si los requisitos comienzan a ser realmente grandes / complicados, es fácil dividirlos en páginas / temas.
• La mayoría de los wikis aceptan HTML, por lo que si realmente necesita un formato avanzado, probablemente pueda usar una herramienta como Windows Live Writer .

Dada la opción, casi siempre elijo el método wiki en estos días, en realidad es bastante indoloro en comparación con los documentos de Word anticuados o tratar de meterlo todo en un rastreador de errores.

Siempre uso IEEE Std 830-1998 (Práctica recomendada de IEEE para especificaciones de requisitos de software) como plantilla para mi documento SRS. Ver http://standards.ieee.org/reading/ieee/std_public/description/se/830-1998_desc.html

El documento final de SRS en sí mismo generalmente es un documento único de OpenOffice.org, pero generalmente hay muchas partes constitutivas que lo incluyen, incluidas hojas de cálculo y diagramas.

Normalmente pongo todos estos documentos juntos en un repositorio que pongo en un sistema de control de revisión , como SVN o CVS. Todos los demás analistas de negocios, diseñadores, desarrolladores, evaluadores, gerentes de proyectos y clientes tienen acceso a este repositorio, para que puedan leerlo y realizar ediciones.

Recuerde, el SRS es un documento vivo y en evolución. Continuará cambiando y creciendo por algún tiempo. No solo es importante que todas las partes interesadas tengan acceso al SRS, sino que también es importante tener un historial completo de los cambios y la capacidad de revertir estos cambios, si es necesario. Entonces, un sistema de control de revisión funciona muy bien para este propósito. ¡Buena suerte!

El uso del rastreador de errores para la gestión de requisitos tiende a ocultar la falta de colaboración y comunicación dentro de la empresa.

Sin juzgar ningún método en particular:

• Si va a utilizar cascada, necesita documentos bien estructurados, precisos y de varias páginas (no un párrafo que mucha gente suele escribir como descripción de un error). Estos documentos también son imposibles de escribir y mantener a un nivel de calidad decente si el personal de marketing / ventas (que originan los requisitos) no funcionan bien junto con el personal de ingeniería.
• Si va a utilizar uno de los métodos ágiles, una unidad de requisitos es una historia de usuario, representada por una tarjeta de historia. La tarjeta en sí no es un requisito, solo un punto de partida de la conversación.

Una (breve) experiencia de uno de mis empleadores anteriores con el uso de un rastreador de errores para los requisitos fue que le dio a muchas personas una forma muy fácil de dejar de comunicarse por completo. La gente simplemente escribiría un deseo, lo arrojaría en el rastreador de errores y supondría que eventualmente se haría realidad.

Por supuesto que lo hicieron sin tener en cuenta:

• sus propias calificaciones
• su participación en el proyecto
• conflictos con otros requisitos
• lagunas en los requisitos
• costos
• cualquier consideración técnica
• etc.

Creo que los documentos de "Word" son la forma incorrecta de cumplir los requisitos, por las siguientes razones:

1. No hay forma de "diferenciar" dos documentos para ver qué ha cambiado.
2. La interfaz de usuario desalienta el uso de un estilo consistente en todo momento. Sí, se puede usar estilos, pero a la mayoría de las personas no se les puede molestar debido a la dificultad.
3. El formato del documento está esencialmente oculto. Claro, hay una especificación para los archivos OLE, que supongo que son documentos de "Word", pero Microsoft ha enterrado todo lo útil bajo toneladas de ruido, por lo que nadie lo sabe realmente. Tarde o temprano, su nueva y brillante "Palabra" no abrirá el documento.
4. No juega bien con otros formatos. Es decir, a menos que use Windows e IE, no tiene suerte si alguien organizó los documentos de un proyecto en archivos HTML con enlaces a archivos en formato "Word". Haga clic en el enlace equivocado y tendrá que pasar por un largo período de descarga e inicio de Word, interrumpiendo el flujo de pensamiento. Los hipervínculos de documentos de "Word" a otros pueden o no funcionar.
5. "Word" es básicamente para escribir documentos destinados a aparecer en papel. Un objetivo admirable, pero que lo hace menos útil para la visualización en línea.

No tengo una sugerencia alternativa con la que tenga experiencia, pero he pensado en el Texto reestructurado de Python o Markdown como alternativas.

Generalmente usamos Word, pero en realidad cómo los crea en el software es menos importante que cómo recopila los datos para crearlos y si la persona que recopila la información sabe lo suficiente como para saber cuándo un requisito es demasiado complicado y será mucho más costoso que un requisito más simple y sin embargo no agrega valor real a nadie (como cuando quieren que los números de identificación se asignen siempre en orden sin omitir ninguno) o cuando entra en conflicto con un requisito existente u otra característica planificada. A menudo, nunca se habla con los usuarios reales y hay muchas sorpresas cuando sus gerentes no sabían algo que tenía que hacerse absolutamente y no está en la nueva versión del software.

También podemos usar varios archivos pdf, Excel o Visio. Todos ellos para el proyecto se recopilan y editan fuera de SharePoint, por lo que podemos ver versiones anteriores si es necesario.

Mantengo una cartera de productos (uno por proyecto o producto) que contiene Historias de usuarios . Se pueden almacenar en software de seguimiento de errores como el que usa. Personalmente uso Excel para el trabajo atrasado y Trac para el trabajo atrasado de sprint (probablemente use una herramienta como esa herramienta).

Solo cuando es necesario, creo un documento de Word que describe la historia del usuario con más detalles y lo adjunto a la historia del usuario. Pero trato de evitar esto dividiendo la historia del usuario en otras más pequeñas.

Las historias de usuarios pequeños son más fáciles de administrar (incluida la estimación)

Me gusta el documento de Word porque me permite poner enlaces, formatear textos, poner tablas, capturas de pantalla y más, y todos pueden leerlo.

Por supuesto, cada historia de usuario se explica en detalle en la sesión de estimación y en la planificación del sprint, y siempre estoy disponible para más preguntas cuando el desarrollador decide trabajar en ella. Las retroalimentaciones frecuentes que utilizan la revisión de sprint evitan que los desarrolladores hagan algo diferente a lo solicitado por el propietario del producto.

Personalmente, en el pasado he usado documentos de Word, pero he resuelto encontrar una herramienta en el futuro para administrar esto por mí ... especialmente con la capacidad de corregir errores según los requisitos, porque muchas veces, el error es en los requisitos, no la desviación entre las especificaciones y la implementación.

Nunca se me ocurrió usar una herramienta de seguimiento de errores, pero tiene mucho sentido.

Por curiosidad, ¿qué es lo que no te gusta?

EDITAR: una advertencia; dígale a su gerente que cambie el nombre del software de seguimiento de errores. De lo contrario, se supone que todo lo que contiene es un error. Tuve este problema político en mi último cliente, donde puse tareas en el rastreador de errores. No está bien.

Escribí una base de datos de requisitos hace 6 o 7 años para manejar esto. Cada registro de requisitos tiene una breve descripción, un memo de "definición" y un memo de "notas" (ambos texto enriquecido, con capacidad para incrustar capturas de pantalla, etc.). También hay otros campos, para proyecto, entregable, número de secuencia (para que se puedan ordenar lógicamente), caso de uso / función con la que está relacionado, tiempo estimado, un campo para la persona que lo maneja, si alguien lo ha seleccionado para la implementación, etc.

También hay un "Estado" - "Entró", mientras diseñamos las características; "Aprobado", establecido una vez que se revisa un grupo de requisitos y se determina que están listos para implementar; "Implementado", establecido por el programador una vez que piensan que se ha cumplido el requisito, y "Validado" una vez que el técnico de control de calidad está de acuerdo con el programador. (Si el técnico de control de calidad no está de acuerdo, puede volver a configurarlo como "Aprobado" para que el programador lo recupere). Los requisitos también pueden ser "Diferidos", "Rechazados" o "Cuestionados" (lo que significa que la Junta de Control de Cambios debe considerarlo .)

El truco para hacerlo bien es una granularidad razonable. A veces puede tener sentido tener requisitos de una oración (por ejemplo, "el problema descrito en el problema 12345 es fijo"), pero en general, los requisitos deben describir todos los aspectos importantes de una característica completa (o una gran parte de una). Por ejemplo, una característica típica de "nuevo informe" tendrá un requisito para un formato de informe (cómo se ve la salida) y un requisito para el cuadro de diálogo de opciones (explicando los campos, validación, etc.) Incluso podría haber un tercero si Hay un generador complejo que procesa los datos, en lugar de una simple consulta o algo así. Además, crearemos un requisito de "Ayuda" para el tema de ayuda correspondiente.

Hay grandes ventajas de mantener estas cosas en los registros de la base de datos en lugar de un gran documento. Varios programadores pueden estar trabajando en los requisitos al mismo tiempo. Los registros individuales están bloqueados para que solo una persona pueda editar a la vez, pero se pueden abrir y leer mientras alguien más está editando. Sin embargo, la mayor ventaja es que proporciona documentación fácil de buscar sobre cuáles eran los requisitos y notas sobre cómo se implementaron. Tenemos más de 25,000 requisitos allí ahora, y podemos encontrar fácilmente todos los requisitos con palabras específicas en todos los campos, o la definición, o notas, o lo que sea, en menos de 10 segundos. (Pruebe con más de 6 años de documentos de Word).

Puedo ver por qué la gente podría decir que es una mala idea hacer requisitos en un "rastreador de errores", pero supongo que es porque las herramientas apestan, no porque mantener los requisitos en una base de datos de búsqueda es una mala idea.

Una vez utilicé http://www.pivotaltracker.com/ pero en mi compañía actual estamos usando .doc como fuente de especificación central y Lighthouse como lista de deseos de características combinadas y seguimiento de problemas. Para mí es difícil hacer que otras personas en el equipo comiencen a usar otras herramientas cuando están tan acostumbrados a Word.

Si puede seguir la metodología ágil, los siguientes enlaces pueden guiarlo a través de la elección de una buena herramienta de gestión de proyectos ágiles:

• Herramientas de gestión de proyectos ágiles
• Comparación de diferentes herramientas de gestión de proyectos ágiles

Y en serio, pruebe la metodología Agile: predica un enfoque simple, elegante, sin sentido, sin sentido del jazz y común en lo que sea que haga, de modo que cada miembro del equipo entienda y aprecie el papel y el esfuerzo de todos los demás miembros.

¡Buena suerte!