Como documentar regras de negócios

Gostaria de saber qual seria o método formal e o mais comumente praticado para documentar as regras de negócios? Além disso, como você documenta as especificações da interface do usuário de artefatos de desenvolvimento (por exemplo, Documentando campos de formulário e como os botões se comportam no formulário, texto informativo etc.)

Para as regras de negócios, acho que o @Joppe apontou para a UML que todos estávamos pensando.

Os diagramas de casos de uso oferecem uma excelente visão geral de como os atores / funções interagem com o sistema e o que o sistema faz. Para complexe Use Case, informações adicionais explicou textualmente vai ajudar muito ( pré-condições , pós-condições , dependências sobre execuções UC anteriores , etc )

Existem diagramas que também oferecem excelentes visões gerais dos negócios em diferentes níveis:

• Diagrama da máquina de estado se houver algum tipo de estado a ser documentado.
• Diagrama de atividade . Para Caso de Uso complexo, pode ser necessário aprofundar os detalhes. O nível dos detalhes depende de você e depende de quem vai ler a documentação. Essa pode não parecer uma documentação comercial, mas com o nível certo de detalhes, pode ser que isso aconteça.

Apenas um conselho, atribua um código a cada Caso de Uso (por exemplo: UC-1 , UC-n ). Estes serão úteis mais tarde, durante a documentação da interface do usuário.

Para a documentação da interface do usuário, a prática comum (atualmente) é fazer wireframes . Muito melhor do que as capturas de tela porque parece mais limpa e mais simples. Por exemplo, dê uma olhada no WireframeSketcher

Os wireframes podem não ser documentação suficiente; portanto, para cada tela, faça uma breve introdução e descreva cada botão. Além disso, faça referências à UC envolvida na tela ( veja agora por que os códigos UC são úteis ). Isso tornará sua documentação coerente.

O objetivo de ferramentas como o Wireframesketcher é que eles fazem maquetes interativas. Perfeito para oferecer algo interativo ao cliente enquanto você ainda está projetando ou desenvolvendo.

Não se esqueça de documentar o plano de navegação . Nav. O plano não possui diagrama UML, mas o State Machine Diagram pode ser usado. Não é para o que foi feito, mas ainda assim.

Por fim, lembre-se de quem você está se dirigindo.

• Técnico : você pode se aprofundar nos detalhes e usar detalhes técnicos.

• Não técnico : evite detalhes técnicos (nem relacionados à linguagem nem ao código). Tente ser claro e simples e use os mesmos termos / palavras que o cliente usa. Pense como se você não tivesse ideia de programação.

A documentação geralmente é feita em casos de uso e outras formas de prosa. Além disso, pode ser extremamente útil ter diagramas UML e outras formas gráficas que oferecem uma visão geral em um nível superior e são fáceis de entender em menos tempo do que a leitura de páginas e páginas.

E por último, mas não menos importante, a melhor documentação imho são os casos de teste que executam as regras de negócios. Dessa forma, você pode alterar o código e descobrir que está violando uma regra de negócios. Caso contrário, a documentação estará sempre sob o risco de ficar obsoleta e desatualizada.

Provavelmente a forma mais comum é Casos de Uso . Você pode complementá-los com modelos e descrições de tela.

Um livro que eu recomendo é "Escrever casos de uso eficazes", de Alistair Cockburn. Ele descreve como você pode escrever casos de uso em vários níveis de detalhes, como evitar cair na abordagem orientada por 'modelo' e apenas manter a documentação dos bits necessários e relevantes.

Qualquer que seja o método usado, verifique se eles podem ser mantidos ativamente. Eles devem ser documentos vivos. A hospedagem dos documentos em um sistema de controle de versão ou em algum tipo de sistema de gerenciamento de documentos como o Sharepoint pode ajudar bastante a mantê-los. Manter o controle das regras de negócios através de documentos do Word anexados a e-mails é uma maneira horrível de lidar com o problema, pois leva a várias versões flutuando.

Eu recomendo separar estritamente as regras de negócios da especificação do sistema, referindo apenas as regras de negócios do caso de uso e design da interface do usuário. Minha técnica favorita é: - Ter uma lista de regras de negócios identificadas em uma planilha. - No design do sistema, especificação de caso de uso, histórias do usuário ou qualquer outra coisa, basta especificar "O usuário digita as informações conforme especificado na regra de negócios BR012", "O sistema calcula o valor total conforme especificado na regra de negócios BR510". Eu recomendo este artigo http://www.allaboutrequirements.com/business-rules/

Tente gerar o diagrama UML usando o código do visual studio e o plug-in Plant UML