“I write to better understand what I said."
—Philippe Krutchen
Business analysts are expected to be the ones who will create plenty of documentations that will guide the design, implementation and maintenance phases of a system. Documents varies from Business Requirement Documents (BRDs), Functional Requirement Documents (FRDs), System Requirement Document (SRDs), Project vision Document, Requirement Management Plan and other. Also a business analyst may contribute to the formation of a Request for Proposal (RFPs), validate and comment on contracts and write user manuals and other type of explanatory documents regarding a solution. It is crucial the documentation created to add value. Every party that has access to documentation must find easily what is looking for and after reading it to gain specific knowledge and understanding of a specific issue.
As a business analyst you will have to decide how will present the information in a document in order to maximize value for he readers. Include diagrams, screenshots, pictures, as well as text descriptions at your documents. Apply what is suitable taking into account the context and the specific characteristics of the project. Tailor any template or approach to the specific context. The solution team will use the diagrams more than the words, especially since they are most likely going to render the words into diagrams for development anyway. The business community may relate to a drawing of a screen layout better than to a three-page textual description of the same screen layout.
The Audience
Defining the audience of your document is necessary in order to use the proper language, the proper format, structure and other aspects. The audience for the document you are preparing may be anyone stakeholder engaged directly or indirectly with the project. Also keep in mind that the document created can be used in future as an elicitation way of future project.
A main group you must have in mind while you preparing a documentation concerning requirements is the design team. Many business analysts assume that the audience is the product stakeholders because they are the ones who confirm and approve. And, yes, the user community needs to be able to understand the document so that they can confirm and approve, but consider this: After the document has been approved and implementation is under way, what do the stakeholders do with the document? The developers’ team is possible to read a requirements document thoroughly, and use it as their guideline for development, testing, and so forth. Once the product stakeholders approve the document they have no further interest in it except perhaps to compare the results at the end.
May it is wise to consider the developer while you are preparing a functional requirements or solution design document with the developer in mind. The glossary, for example, should contain business terms rather than the technical ones we might be tempted to include for the business community's understanding.
If you think that the ultimate audience for your solution document or requirements is the business community, consider the last time you wrote requirements for implementation. After a couple weeks or months, what is the solution team doing with the requirements (or the user stories, or the product backlog)? They are reading them, discussing them, analyzing them, tearing them apart and so forth. What are the product stakeholders who signed off doing with the document? Using it as a doorstop, piling it with a stack of reports from 2001, putting it under the shorter table leg to balance the table in the coffee room, and in general ignoring it. It's rare that the requirements even reappear in the business community at acceptance test time. They don't care if it matches the requirements, just that the delivered system solves their problem.
Quality Criteria
A high quality requirements document contains valid requirements. Valid requirements must meet, as much as possible, the following criteria:
Creating the solution document is the act of rendering the requirements into a format that complies with these criteria.
Each form of the document has its own guidelines. For example, a use case description typically contains the following information:
- Actors (both primary and supporting)
When you are creating a formal solution document such as a business requirements document (BRD), functional requirements specification (FRS), system requirements specification (SRS), and the like, there is a formula for creating a well-formed functional requirement. Note that this does not apply to nonfunctional requirements.
A typical functional requirement contains the following structure:
- Condition (if, when, while, during, etc.)
- Imperative (will, shall, must, etc.)
A functional requirement might look like this:
When the vendor number is entered [condition], the system [subject] will [imperative] display [active verb] the vendor name and address on the screen [object] (see Figure 2.1) as long as the vendor is current [business rule] for visual verification [outcome] (note that the last two phrases are somewhat of a stretch for purposes of demonstration).
Figure 2.1 in the requirements document contains the details of what the screen looks like.
The same approach is applied when using user stories. The user story typically has this format:
As a [type of user], I want [some particular feature] so that [some benefit is received].
The requirement above might be rendered as the following user story:
As an accounts payable voucher enterer [type of user], I want the vendor name and address displayed when I enter the vendor number [feature] so that I can visually verify I entered the right vendor number [benefit received].
Details of what the screen looks like and where the information is displayed are worked out between the developer and user.
Remember…
In the end the important element in writing a document is that it is understandable the same way by everyone with an interest in reading it.
Do not let documentation substitute for real communication. A solution document is only one of several techniques the business analyst uses to ensure that a consensus exists among all stakeholders.
Many business analysts get seduced by the necessity to deliver certain documents. Many are actually evaluated based on the business analysis documents they produce. They start making the document the primary outcome of their work. They believe that the document is also a way of perpetually assessing the author's abilities and productivity, so most of their focus and attention goes to perfecting the document in both content and form. Naturally the document contains the results of gathering information from the stakeholders. However, when the document is the end result of the business analyst's activities, more time is spent between the business analyst and the document than between the business analyst and the stakeholders. Ironically, focusing on the document tends to reduce the flow of information.
Author: Giorgos Sioutzos ITIL, CCBA, PRINCE2 – Business Analyst, Consulting Industry | CCBA
Giorgos Sioutzos is working in the business consulting industry as a business analyst. He has experience in projects from different sectors. He holds a BSc in Management Science and Technology from Athens University of Economics and Business and Msc in International Business & Management. Numerous articles about business and technology issues have been published in most reputable Greek and foreign media.