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)

  • "Formal" is rarely the "best way" . Your title is confusing me :-P – Joppe Jun 28 '11 at 18:59
  • I have changed it, I hope that is less confusing :) – Maro Jun 28 '11 at 19:04
  • Technical doc or functional doc? Who is going to read this documentation? – Laiv May 18 '16 at 17:17

For business rules I think @Joppe pointed out to the UML we all were thinking.

Use Case Diagrams does an excelente overview of how Actors/Roles interact with the system and what system does. For complexe Use Case, additional info explained textually will help a lot (preconditions,postconditions,dependencies on previous UC executions,etc)

There are diagrams that also does great overviews of the business at different levels:

  • State Machine Diagram if there's any sort of states to be documented.
  • Activity Diagram. For complexe Use Case you may need to go deep into details. The level of the details is up to you and depends on who is going to read the documentation. This one may not seem business-like documentation, but with the right level of details it could become so.

Just an advice, assign a code to each Use Case (i.e: UC-1, UC-n). These will be useful later, during UI documentation.

For UI documentation the common practice (these days) is to do wireframes. Quite better than screen-shots because it looks cleaner and simpler. For instance, take a look at WireframeSketcher

Wireframes may not be enough documentation, so, for each screen do a brief introduction and describe every button. Additionaly, do references to the UC involved into the screen (see now why UC codes are useful). This will make your documentation coherent.

The point of tools like Wireframesketcher is that they do interactive mockups. Perfect to give something interactive to the customer while you are still designing or developing.

Don't forget to document the navigation plan. Nav. Plan doesn't have UML diagram, but State Machine Diagram can be used instead. It's not for what it was made, but still.

Finally keep in mind who you are addressing to.

  • Technician: you can go deep into details and to use technicalities.

  • Not Technician: avoid technicalities (neither related to languaje nor code). Try to be clear and simple and use the same terms/words that customer uses. Think like you had no idea of programming.

| improve this answer | |

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.

| improve this answer | |

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.

| improve this answer | |

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.

| improve this answer | |

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/

| improve this answer | |

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

| improve this answer | |

Not the answer you're looking for? Browse other questions tagged or ask your own question.