specifications - estilo - ¿Qué hace una buena especificación?

manual de estilo ejemplo (12)

Como alguien que desarrolla software personalizado para clientes, la mejor especificación es la que el cliente ha firmado .

No importa qué tan refinada sea su especificación; si el cliente no ha aceptado explícitamente por escrito, la cambiarán y esperan que usted desarrolle sus cambios a la perfección, arruinando su hermosa arquitectura ...

Uno de los elementos en el Test Joel es que un proyecto / compañía debe tener una especificación.

Me pregunto qué hace que una especificación sea buena. Algunas compañías escribirán volúmenes de especificaciones inútiles que nadie jamás leerá, otros no escribirán nada porque "de todos modos, nadie leerá nada". Entonces, ¿qué pones en tu especificación? ¿Cuál es el buen equilibrio entre los dos extremos? ¿Hay algo particularmente importante que realmente, realmente (!) Debería registrarse siempre en una especificación?

Creo que escribir "Casos de uso" debería ahorrarle un montón de páginas

Depende de qué tan grande es el proyecto y (como todas las decisiones de arquitectura) cuáles son las limitaciones. Un buen comienzo es

una breve descripción, un "buscapersonas"
un diagrama de contexto: ¿dónde están los límites, qué interactúa con el sistema?
casos de uso / historias de usuarios
un prototipo de GUI o prototipo de papel, si corresponde
una descripción de los requisitos no funcionales necesarios (rendimiento, etc.)

Lo mejor de todo es tener una prueba de aceptación, es decir, una declaración comprobable de las cosas que se pueden verificar, junto con un acuerdo de que cuando se hagan esas cosas, el proyecto estará completo.

En mi experiencia, una especificación tendrá más posibilidades de ser leída si tiene lo siguiente:

Usa diagramas donde sea posible - las imágenes valen 1000 palabras
Tener una página de título que indique claramente lo que está describiendo la especificación
Tener un estilo que se usa en todo el documento. Haz que todos los encabezados tengan la misma fuente, tamaño y estilo. Haga que la fuente sea la misma durante todo el proceso, use los mismos estilos de viñetas, etc.
NO HACER WAFFLE: sea claro, conciso y directo, y no agregue cruft extra para rellenar su documento. Si un punto no puede explicarse en unas pocas líneas de texto, entonces tal vez deba descomponerlo aún más

Lo he visto en compañías donde la persona que escribe las especificaciones no entiende el sistema. Es casi una forma de aprender el sistema escribiendo la especificación. Esto generalmente termina en lágrimas ...

La mejor especificación es aquella que:

Existe
Describe QUÉ, no CÓMO (sin soluciones)
Puede ser interpretado de la menor cantidad posible
Está ampliamente distribuido
Está acordado como la especificación de todas las partes involucradas
Es conciso
Es consistente
Se actualiza regularmente a medida que cambian los requisitos
Describe tanto del problema como sea posible y práctico
Es comprobable

Las buenas especificaciones deben contener requisitos que sean medibles y verificables. Al analizar cada requisito, debería ser capaz de responder fácilmente la pregunta: "¿Cómo puedo demostrar que he cumplido con este requisito?".

Lea la serie de seguimientos de " Especificaciones funcionales sin dolor " de Joel en el artículo de Joel Test. También aparecen en el libro "Joel on Software".

Un plan que describe toda la información crítica necesaria para la implementación, pero no desperdicia ningún esfuerzo en describir toda la información trivial u obvia que también es necesaria.

Simplemente debería ser suficiente información para asegurar que la implementación sea "como se esperaba", sin proporcionar demasiado ruido adicional que no es necesario.

En la práctica, la mayoría de las personas lo malinterpreta, ya que se concentran en lo fácil (que es lo menos necesario) y se alejan de las cosas difíciles (que es lo que realmente quiere bloquear). He visto demasiados documentos de 2 pulgadas que omiten por completo y completamente el punto, y muy pocos de 3 páginas que llegan a la muerte.

Las especificaciones no tienen que ser largas, ¡solo tienen que contener las cosas correctas!

(sugerencia: si el programador no miró esa página mientras codificaba, probablemente no era necesario)

Pablo.

También ayuda si comienzas indicando el objetivo que tiene el usuario o cuál es la idea global de una determinada función; en lugar de completar la implementación exacta. Esto siempre me parece como reducir la mentalidad abierta o usar soluciones menos creativas (más útiles). Por lo tanto, debe mantener "todas las opciones abiertas".

Ejemplo : escribir un software para medir "X".

En lugar de indicar: tiene que haber un botón de inicio y un botón para guardar.

Uso: el usuario debe poder iniciar una medición y guardarla.

Por qué ? Porque en la primera situación ya determinó cuál debe ser la solución, mientras que la segunda situación le da flexibilidad sobre cómo implementar algo. Ahora esto puede parecer trivial, pero tengo la sensación de que los "programadores" tienden a pensar más en soluciones que en problemas (o situaciones). Cuando agrega más funcionalidad, esto se vuelve más obvio, porque entonces podría haber sido mejor usar un asistente o automatizar el proceso, pero ya redujo la idea a usar botones.

Para requisitos funcionales, o más específicamente, requisitos de comportamiento, me gusta usar pepino y pepinillo.

Aquí hay un ejemplo de una especificación simple y corta para una nueva característica en una aplicación de mapeo simple. La característica permite a las pequeñas empresas suscribirse a la plataforma de mapeo y agregar sus lugares de negocios en un servicio similar a Google Maps.

Esta especificación parece engañosamente simple, pero de hecho es bastante poderosa.

Las buenas especificaciones son claras, inequívocas y concretas. No es necesario descifrarlos para escribir el código de trabajo. Eso es exactamente lo que son las especificaciones de Gherkin. Lo mejor es que sean breves y simples. En lugar de escribir un documento de especificación larga, permite que la suite de especificaciones evolucione junto con su producto escribiendo nuevas especificaciones en cada iteración.
Gherkin es un lenguaje legible por negocios para escribir documentos de especificación basados en la plantilla de Dado-Cuando-Luego. La plantilla se puede automatizar en pruebas de aceptación. La automatización de la especificación garantiza que se mantenga actualizada porque la conversación capturada está directamente relacionada con el código de prueba. De esta forma, las pruebas se pueden usar como documentación, porque las características de Gherkin tienen que cambiar cada vez que cambia el código.
Cuando cada regla de negocio recibe una prueba automatizada, las especificaciones de Gherkin se convierten en las llamadas especificaciones ejecutables: especificaciones que se pueden ejecutar como programas de computadora. El programa prueba si los criterios de aceptación se implementaron correctamente. Entonces, al final del día, obtenemos una respuesta de sí o no a la pregunta de si nuestro producto está realmente haciendo lo que esperamos que haga, lo que en sí mismo es muy valioso, ya que contribuye a crear software de mejor calidad. .
La conexión directa entre las especificaciones de Gherkin y el código de prueba a menudo reduce el daño de los desechos al crear y cultivar un sistema de documentación de vida. Gracias a la validación frecuente de las pruebas, como en los sistemas de integración continua, puede saber que Given-When-Thens está actualizado y, cuando confía en sus pruebas, puede utilizar las especificaciones de Gherkin correspondientes como documentación para todo el sistema.
De hecho, hay una metodología completa llamada Especificación por ejemplo que usa herramientas como Gherkin. La especificación de las prácticas de Example reduce la posibilidad de malentendidos y reelaboraciones al proporcionarle un marco para hablar con las partes interesadas del negocio al obligarlo a utilizar ejemplos concretos, discretos e inequívocos en sus documentos de especificación.

Si desea leer más sobre Cucumber, Gherkin, BDD y Especificación por ejemplo, escribí un libro sobre el tema. "Writing Great Specifications" explora el arte de escribir grandes escenarios y lo ayudará a convertir las especificaciones ejecutables en una parte central de su proceso de desarrollo.

Si está interesado en comprar "Escribir excelentes especificaciones", puede ahorrar un 39% con el código de promoción 39nicieja2 :)

+1 @ KiwiBastard y yo agregamos escribir como una viñeta y hacer que cada viñeta sea comprobable.

Qué poner en una especificación

Debe mirar a la audiencia de las especificaciones y averiguar qué es lo que necesitan saber. ¿Es solo un documento entre usted y un patrocinador de negocios? En este caso, probablemente sea bastante liviano. Si se trata de una especificación funcional para un proyecto J2EE de más de 100 años-hombre, probablemente necesite un poco más de detalle.

La audiencia

La pregunta clave es: ¿quién va a leer las especificaciones? Una especificación tendrá varios conjuntos potenciales de partes interesadas:

El dueño del negocio que está firmando el sistema.
El desarrollador que está construyendo el sistema (que puede ser o no tú)
QA personas que tienen que escribir planes de prueba para ello.
Personal de mantenimiento que quiere entender el sistema
Desarrolladores o analistas de otros proyectos que deseen integrar otros sistemas en él.

Requisitos de las partes interesadas clave típicas:

El propietario de la empresa debe tener una idea clara de los flujos de trabajo del sistema y las reglas comerciales para poder tener la oportunidad de comprender lo que han acordado. Si son la única audiencia principal de la especificación, concéntrese en la interfaz del usuario, el flujo de trabajo de la pantalla y las reglas de validación de negocios y datos.
Los desarrolladores necesitan un modelo de datos, reglas de validación de datos, una parte o la totalidad del diseño de la interfaz del usuario y una descripción suficiente del comportamiento esperado del sistema para que sepan qué construir. Si está escribiendo para desarrolladores, concéntrese en la interfaz de usuario, mapeando el modelo de datos y las reglas en la interfaz de usuario. Esto debería ser más detallado que si estuviera haciendo el desarrollo usted mismo porque está actuando como intermediario en una comunicación entre dos terceros.
Si está especificando una interfaz entre dos sistemas, esto tiene que ser muy preciso.
El personal de QA necesita suficiente información para determinar cómo probar y validar la lógica, la validación y el comportamiento esperado de la interfaz de usuario de la aplicación. Una especificación destinada a desarrolladores y personal de control de calidad debe ser bastante inequívoca.
El personal de mantenimiento necesita la misma información que los desarrolladores, además de un documento de hoja de ruta del sistema que describe la arquitectura.
Los integradores necesitan un modelo de datos y definiciones claras de cualquier interfaz.

Componentes clave de una especificación:

Supongo que uno está escribiendo especificaciones para aplicaciones comerciales, por lo que el contenido a continuación está orientado a esto. Las especificaciones para otros tipos de sistemas tendrán un énfasis diferente. En mi experiencia, los elementos clave de una especificación funcional son:

Interfaz de usuario: maquetas de pantalla y una descripción del comportamiento de interacción del sistema y el flujo de trabajo entre pantallas.
Modelo de datos: Definición de los elementos de datos y mapeo a la interfaz de usuario. Las asignaciones de interfaz de usuario normalmente se realizan en los bits de la especificación que describe la interfaz de usuario.
Validación de datos y reglas comerciales: qué verificaciones de corrección deben hacerse en los datos y qué cálculos se están realizando, junto con las definiciones. Los ejemplos pueden ser bastante útiles aquí.
Definiciones de interfaces: si tiene interfaces expuestas que otros sistemas pueden usar, debe especificarlas bastante bien. Los RFC de Internet más simples dan ejemplos bastante buenos de diseños de protocolos y son un buen comienzo para ejemplos de documentos de interfaz. Definir claramente las interfaces no es fácil, pero casi seguro le ahorrará dolor por la pista.
Pegamento: aquí es donde ayudan los casos de uso, diagramas de flujo de trabajo y otros artefactos relacionados con los requisitos. En general, una lista exhaustiva de estos no tiene sentido, pero habrá áreas clave dentro del sistema donde este tipo de documentación ayuda a poner los elementos en contexto. Mi experiencia es que la inclusión selectiva de casos de uso y otras descripciones de niveles de requisitos hace mucho para agregar claridad y significado a una especificación, pero escribir una historia de usuario para cada interacción individual con el sistema es una pérdida de tiempo.

Joel (de la fama del software) escribió una buena serie de artículos sobre esta llamada Especificación funcional sin dolor a la que he referido a personas en bastantes ocasiones. Es un conjunto bastante bueno de artículos y vale la pena leerlo. En mi opinión, su objetivo es explicar claramente qué se supone que debe hacer el sistema de una manera que minimice la ambigüedad. Es bastante útil pensar en la especificación como un documento de referencia: lo que las diversas partes interesadas podrían buscar fácilmente.

Después de haber escrito un conjunto simplista de viñetas sobre las especificaciones, la parte de comunicación clara es más difícil de lo que parece. Las especificaciones son en realidad documentos técnicos no triviales y son una gran prueba de la escritura técnica y las habilidades editoriales. En realidad, se dedica a escribir un documento que describe lo que se supone que debe construir alguien. Hacer buenas especificaciones es un poco de arte.

El pago por hacer especificaciones es que nadie más quiere hacerlas. Como ha escrito lo que probablemente sea el único documento de importancia para el sistema, tiene que tomar las decisiones. Cualquier persona con una agenda tiene que presionarlo para cambiar la especificación o de alguna manera imponer una especificación competitiva en el proyecto. Este es un buen ejemplo de que la pluma es más poderosa que la espada.

EDITAR: Ha sido mi experiencia que el debate sobre la distinción entre "cómo" y "qué" tiende a ser bastante egoísta. En cualquier proyecto no trivial, el modelo de datos y la interfaz de usuario tendrán múltiples partes interesadas, no todos los desarrolladores del sistema. Trabajar en el almacenamiento de datos le dará el gusto por el caos que se produce cuando un modelo de datos de aplicación puede convertirse en una opción gratuita, y PFS debe darle una idea del conjunto potencial de partes interesadas a las que debe atender una especificación.

El hecho de que alguien posea un modelo de datos o un diseño de interfaz de usuario no significa que estos simplemente se decidan por decreto; puede haber un discurso y un proceso de negociación. Sin embargo, a medida que un proyecto se hace más grande, el valor de la propiedad y la coherencia en estos se hace mayor. Ha sido mi observación en el pasado que la mejor manera de apreciar el valor de un buen analista es ver el daño hecho por uno malo.