Cómo documentar las reglas comerciales

Me pregunto cuál sería el método formal y más practicado para documentar las reglas de negocio. Además, ¿cómo documenta las especificaciones de la interfaz de usuario de los artefactos de desarrollo (por ejemplo, documentar campos de formulario y cómo se comportan los botones en el formulario, texto de información, etc.)

Para las reglas comerciales, creo que @Joppe señaló el UML que todos estábamos pensando.

Use Case Diagrams ofrece una excelente descripción de cómo los actores / roles interactúan con el sistema y qué hace el sistema. Para casos de uso complejos, la información adicional explicada textualmente será de gran ayuda ( condiciones previas , condiciones posteriores , dependencias de ejecuciones UC anteriores , etc. )

Hay diagramas que también ofrecen excelentes descripciones del negocio en diferentes niveles:

• Diagrama de máquina de estados si hay algún tipo de estado que se debe documentar.
• Diagrama de actividad . Para casos de uso complejos, es posible que deba profundizar en los detalles. El nivel de los detalles depende de usted y depende de quién va a leer la documentación. Puede que esta no parezca una documentación empresarial, pero con el nivel adecuado de detalles podría serlo.

Solo un consejo, asigne un código a cada caso de uso (es decir: UC-1 , UC-n ). Estos serán útiles más adelante, durante la documentación de la interfaz de usuario.

Para la documentación de UI, la práctica común (en estos días) es hacer wireframes . Bastante mejor que las capturas de pantalla porque se ve más limpio y simple. Por ejemplo, eche un vistazo a WireframeSketcher

Las estructuras alámbricas pueden no ser suficiente documentación, por lo tanto, para cada pantalla, haga una breve introducción y describa cada botón. Además, haga referencias a la UC involucrada en la pantalla ( vea ahora por qué los códigos UC son útiles ). Esto hará que su documentación sea coherente.

El punto de herramientas como Wireframesketcher es que hacen maquetas interactivas. Perfecto para dar algo interactivo al cliente mientras todavía está diseñando o desarrollando.

No olvide documentar el plan de navegación . Nav. Plan no tiene diagrama UML, pero en su lugar se puede usar el diagrama de máquina de estado . No es por lo que fue hecho, pero aún así.

Finalmente, tenga en cuenta a quién se dirige.

• Técnico : puede profundizar en los detalles y utilizar tecnicismos.

• No técnico : evite tecnicismos (ni relacionados con el idioma ni el código). Trate de ser claro y simple y use los mismos términos / palabras que usa el cliente. Piensa como si no tuvieras idea de la programación.

La documentación a menudo se realiza en casos de uso y otras formas de prosa. Además, puede ser extremadamente útil tener diagramas UML y otras formas gráficas que le brinden una visión general en un nivel superior y que sean fáciles de comprender en menos tiempo que leer páginas y páginas.

Y por último, pero no menos importante, la mejor documentación en mi opinión son los casos de prueba que ejecutan las reglas de negocio. De esa manera, puede cambiar el código y descubrir que está violando una regla comercial. De lo contrario, la documentación siempre corre el peligro de quedar obsoleta y desactualizada.

Probablemente la forma más común es Casos de uso . Puede complementarlos con maquetas de pantalla y descripciones.

Un libro que recomendaría es "Escribir casos de uso efectivo" de Alistair Cockburn. Describe cómo puede escribir casos de uso en varios niveles de detalle, cómo evitar caer en el enfoque impulsado por la 'plantilla' y limitarse a documentar los bits necesarios y relevantes.

Cualquiera sea el método que utilice, asegúrese de que puedan mantenerse activamente. Deberían ser documentos vivos. Alojar los documentos en un sistema de control de versiones o algún tipo de sistema de gestión de documentos como Sharepoint puede contribuir en gran medida a mantenerlos mantenidos. Hacer un seguimiento de las reglas comerciales a través de documentos de texto adjuntos a correos electrónicos es una forma horrible de abordar el problema, ya que lleva a varias versiones flotando.

Recomiendo separar estrictamente las reglas comerciales de la especificación del sistema al referirme solo a las reglas comerciales del caso de uso y el diseño de la interfaz de usuario. Mi técnica favorita es: - Tener una lista de reglas comerciales identificadas en una hoja de cálculo. - En el diseño del sistema, especificación de casos de uso, historias de usuarios o lo que sea, simplemente especifique "El usuario ingresa la información como se especifica en la regla comercial BR012", "El sistema calcula la cantidad total como se especifica en la regla comercial BR510". Recomiendo este artículo http://www.allaboutrequirements.com/business-rules/

Intente generar un diagrama UML usando el código visual studio y el complemento Plant UML