How to document business rules

Question

I am wondering what would be the formal and the most commonly practiced method of documenting business rules? Also how do you document the UI specifications of development artifacts (e.g. Documenting form fields and how buttons behave on form, info text .. etc)

Answer 1

For business rules, I think @Joppe pointed to the diagram we all were thinking of.

Use Case Diagrams make for excellent overviews of what the system does and how (and how many) actors/roles interact with this system. For complex use cases, UML already considers notes and comments to complete the information, so go ahead with them too. Just a piece of advice, give a code to each Use Case (i.e. UC-1, UC-n) so you can make references to use cases from other documents, for example, the UI documentation.

For UI documentation, wireframes have become a common practice. Quite better than screen-shots because they look cleaner, they are also editable and generate assets you can version. Some tools make'em interactive too. To complete this "documentation", write a brief introduction of each view and describe every button or field involved and do references to the UC (code) involved.

Regarding the UI, document the navigation plan too. Navigation plans have no UML diagram but State Machine Diagram can do the job.

Finally, as with any other documentation, keep in mind its audience

• Technician: you can go deep into details and use a technical language
• Not Technician: avoid technical language. Use the ubiquitous language of the domain (business)

Answer 2

Documentation is often done in use cases and other prose forms. In addition it can be extremely useful to have UML diagrams and other graphical forms that give you an overview on a higher level and are easy to comprehend in a shorter time than reading pages and pages..

And last but not least the best documentation imho are test cases that execute the business rules. That way you can change the code and find out that you are violating a business rule. Otherwise the documentation is always under the danger of becoming stale and out of date.

Answer 3

Probably the most common form is Use Cases. You can supplement them with screen mock-ups and descriptions.

A book I'd recommend is "Writing Effective Use Cases" by Alistair Cockburn. It describes how you can write use cases at various levels of detail, how to avoid falling for the 'template' driven approach, and just sticking to documenting the necessary and relevant bits.

Answer 4

Whatever method you use, be sure that they can be actively maintained. They should be living documents. Housing the documents in a Version Control system or some sort of document management system like Sharepoint, can go a long way towards keeping them maintained. Keeping track of business rules through word documents attached to emails is a horrible way to deal with the issue, since it leads to multiple versions floating around.

Answer 5

I highly recommend to strictly separate the business rules from the system specification by only refering business rules from use case and UI design. My favourite technique is: - Have a list of identified business rules in a spreadsheet. - In the system design, use case specification, user stories or whatever, just specify "The user enters information as specified in business rule BR012", "The system calculates the total amount as specified in business rule BR510". I recommend this article http://www.allaboutrequirements.com/business-rules/

Answer 6

Try generating UML diagram using visual studio code and Plant UML plugin