Dazzle ’em With Your Documentation Style!
Business analysts know it’s always about the what and not the how… or is it? Capturing the what is obviously key, but if the what is all you’ve got in black and white text, it’s highly doubtful that your audience will read it, let alone get it. Clearly it’s not just about what you deliver but how you deliver it. Ask yourself what stands out about a really good message—you’ll be surprised to discover that the delivery can sometimes stick with you just as much or more than the actual message. That’s also true when writing requirements. It’s one thing to document the content but what’s key is how to capture your audience.
If you take your documentation seriously and want to try a few simple things to grab your readers’ attention, you’ll need to take your message and polish it, shine it and essentially dazzle ’em with your documentation style. Not convinced yet? Let’s take a closer look at when to use these simple tips, who would benefit from them and why it’s so important. We’ll even teach you how.
Who is your audience?
So who cares about your document… and what do they care about?
Your audience can range from individuals who need a lot of detail to those who are only concerned with high-level information. Refer to BABOK Figure 1-3: Examples of Generic Stakeholders. For instance, your end users, subject matter experts, testers and programmers typically require things to be spelled out in detail. On the other hand, our project sponsors and executive audience may thrive solely on broader high-level project information.
A Guide to the Business Analysis Body of Knowledge (BABOK Guide). Figure 1-3: Examples of Generic Stakeholders.
The idea here is to capture everyone’s attention, and you can do that if you make your work shine. The trick is to make your document user-friendly by allowing readers to find information quickly and at a glance. A document that includes details and summations, and that is well organized and easy on the eyes, will definitely capture the attention of your entire audience when presented in a user-friendly format. Learn more on how to achieve this in the ‘How do I do this?’ section later in this article.
Where can you use these tips?
The places you can use these tips is unlimited. Use them in:
- business requirements documents (BRD)
- presentations
- emails
- any documentation that you do in your career.
We believe these tips are invaluable personally and professionally.
What can you use these tips for?
Think about the multiple audiences a business analyst needs to capture and satisfy. This role delivers much more than the BRD. From requirement elicitation notes to communication of options, while delivering documentation you should always think, “Have I got their attention?” and “How do I keep their attention?” Continually think about the message you want to convey and what your wow factor is for delivering that message.
When should you do this?
So when does it make sense to polish your documents? Does it make sense for every email you send and every document you write? The simple answer is “yes” but reality will teach you that you need to tailor your efforts and only do what makes sense.
Documentation that shines not only allows you to capture the attention of your audience but it also helps you to effectively communicate your work. Give your documentation the attention it deserves and do it right from the start.
On a project, be sure to continue using dazzling documentation right through BRD completion and when supporting the project team and change management process. In other words, write everything, all the time, as if it were being published.
Ultimately, you always want your documentation to have an impact, whether you are persuading the audience, conveying an understanding, selling an option or outlining business requirements.
Why should you take the time to make your documents shine?
There are so many reasons why but we’ve narrowed it down for you.
You want to make sure your documents grab the reader’s attention and keep it. We’ve all had that experience of a project member (e.g., programmer or tester) asking you a question that is already covered in the business requirements document (BRD). If your BRD shines, you’ll increase the odds of that person actually reading and using your BRD.
Your document also has a place in the future. Although it’s integral to the current project, opportunity or challenge at hand, your documentation becomes a valuable point of reference in the future. Repeatable projects can benefit from your documents that require very little rigor each year.
Other benefits delivered by your shining documentation:
- artifact for future project startups
- training
- living documentation
By using various documentation techniques, your documents become clear, concise and unambiguous. They are easier to maintain and make changes to. Any future audience can understand your document. If your reader gets it, your document is effective and you did your job well.
How do I do this?
And finally, what you’ve all been waiting for… how you get started. We hope that this section will give you some ideas regarding how to make your documents shine.
There are easy things you can implement right away.
- Use white space so it’s easy on the reader’s eyes and visually partitions your document.
- Use lists or tables.
For example, if you are detailing out a new report, instead of using paragraphs or lists, consider using a table.
|
Report Heading |
Description |
Format |
Field Rules / Calculation |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- When making changes to an existing screen, use a screen capture tool to visualize the changes.
- Use colour—just don’t go overboard with it. Using too much colour can be distracting.
There are lots of diagramming techniques you can use that are documented in the IIBA’s BABOK. Diagrams are an excellent way of communicating your requirements. Consider using these techniques:
- data flow diagram
- data modelling
- decision tree
- process modelling
- prototyping
- sequence diagrams
- state diagrams
- SWOT matrix
Using them in the right way and at the right time can be very powerful. It’s like the old adage that “a picture is worth a thousand words.”
To sum things up
We should all take the documenting of requirements seriously. It’s not just what you are putting in your requirements document but how you are delivering the message. It can make the difference between requirements, and requirements that are superior. So, jazz them up and dazzle ’em with your documentation style!
References
A Guide to the Business Analysis Body of Knowledge (BABOK Guide). Version 2.0.
International Institute of Business Analysis. 2009.
Don’t forget to leave your comments below.
Nada Spariosu and Patti Rueffer have 30+ combined years of experience as business analysts within IT departments in financial organizations. Both are IIBA members and have obtained their CBAP certification. Nada Spariosu is a member of the Waterloo-Wellington, Canada chapter of the IIBA.