Documenting your business rules: Where to begin

With a solid system of business rule documentation, business knowledge issues can be avoided, which can lead to smoother projects, better software, and a better bottom line.

By Tim Chapman

How does your company document its business rules? Does your company document its business rules? Questions like these are what project managers should be able to answer without any hesitation; however, this is not always the case. With a solid system of business rule documentation, business knowledge issues are much more likely to be avoided, which can lead to smoother projects, better software, and a better bottom line. If you don't have such a system in place, here are a few tips that might come in handy if you decide to implement one.

Why a business rule repository?

A business rule repository is any system your company uses to document, update, and keep track of the business needs and rules regarding your projects. Having a central repository to store these rules will allow developers and business owners access to rules, and any questions regarding business projects.

As a project manager, you're likely asking yourself why you would need something like this. Of course, all the important information you need regarding your projects are written down in several documents that everyone uses, right? Does everyone who needs to use these documents know where to go to get them? If you had a system where all business rule documentation was placed, everyone would know where to go to research project business rules, update business rules, and use these rules for development needs.

Bugs will always occur in software, something will always be missed. When these bugs do occur, questions arise such as "What caused the bug?" or "How did this get through testing?" Sometimes these bugs are caused by developers and the business missing the business rules.

Where to begin

Developing the methods for which to document your business rule is the most difficult aspect of the process. Here are a few pointers regarding developing the process.

Management Approval

Getting the approval from management for a business rule documentation system is the first step in the implementation of the system. The system cannot be successful unless management agrees to use it. Organize a meeting with the key business leaders to discuss the development of the system. It must be stressed to the business leaders that the system will be a new way for which projects are documented and handled.

Design the Workflow

The workflow of your business rule documentation system will begin with a project manager creating documentation regarding the new project, and any business rules that they are aware of. The document is then passed to the development team for review. The development team should append any questions they have regarding the implementation to the document. Every potential business rule and every question regarding those rules should be fully documented. Having this audit trail will aid both parties during the project.


Deciding the manner in which to store the business rules for others to access it critical to the implementation of a successful system. A variety of options are available, such as using the file system, using version control software such as Microsoft Visual Source Safe, or using a database. The main functionality you want is to be able to audit the changes to the documentation, and to quickly research the documents. In addition, having the ability to enforce security measures could be a big plus in the minds of top management.

Where to go from here

Now that you have an idea of why you should consider using a business rule repository, you should decide if implementation is a fit for you. Discuss the idea with your colleagues. If you can get your colleagues to buy into the idea, then there's a good possibility that you can get management to buy into the idea as well. Make sure you stress the idea that even though the initial costs of implementation may be high, the benefit of company time saved will easily pay for itself.