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)
Documentation – How to Document Business Rules
business-rulesdocumentation
Related Solutions
My only recommendation is to remember the old adage "a picture is worth a thousand words", especially when describing a process. Make liberal use of flowcharts and such instead of long, wordy process descriptions that no one will want to read. The people who use the document will thank you.
Here is some good information on some of the elements that make up a good process flow diagram.
A simple flow chart:
This is one of the major problems with "big-A-Agile" development: it's primarily focused on development. If system documentation matters to your users (and it usually does), your technical writers and their work-product need to be part of the sprint. In the "small-a-agile" community, we've come to understand that there is more to product than just code. We've integrate testers and testing into sprints, including making sure the testers know enough about what is being coded that they can test inside the sprint. We need to do the same with the technical writers, although I don't know anyone who's doing it yet.
Best Answer
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:
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.