As Business Analysts we write a lot of documentation. Most of our documentation comes in the form of text, but many BAs have learned to augment their text documents with a variety of diagrams. The thing that bothers me though, is that too many BAs blindly follow prescribed templates for their requirements artifacts. Rarely do they ask how their requirements documents are being used by stakeholders, testers, and developers.
As a BA, you should always ask these questions of your audience in regards to your documentation:
- How do you use the documentation that I provide?
- What parts of the documentation do you read?
- Do you find the diagrams useful and understandable?
- What parts do you not look at? Why not?
- What can I add to the documentation to get you the information you need?
- Is printed documentation the most effective way to provide you with the information?
- How do you get the missing information? Do you talk directly with users and stakeholders?
- Could I help you do that?
- Are our templates organized in the best way?
- Does the same document work for different audiences (think business vs. development)?
- What’s the consequence if I don’t write some particular document?
We need to justify why we write documentation, not simply follow some template because it’s always been done like that. Too many templates have a “one-size-fits-all” structure that won’t work for some projects. Question the documentation templates and find better ways of communicating your analysis insights.
I believe that we need to look beyond documents as a way of managing and communicating requirements. Too many of my clients still use principally Microsoft Word to track, store, manage, and communicate their requirements. Why not publish the requirements as a Wiki? Why not track the requirements in an actual requirements management tool or at least a database? Why not use the power of the Web and HTML to provide live links and cross references?
Tell us, how do you document your requirements? Do you produce different documents for different audiences? How do you manage these different versions? Do they find them useful? Do you ever ask your developers and vendors how they use your documentation and how you might improve them? Have you considered using Wikis as an alternative to sharing requirements?
Good points, Martin. I tend to use spreadsheets for tracking requirements because it is very fast to create them, but I am a huge fan of databases because they offer so much more flexibility. Putting the work into database creation up front offers valuable benefits as the project progresses.
I agree. Spreadsheets and databases are a huge step forward and really beat Word. There’s little you can do to get any metrics from Word.
We are considering using a Wiki to document the requirements. However, we are not sure how to start and how to organize the information. Would you create a page for each section? Do you have any advise on this?
I have used wikia, Zoho Wiki, wetpaint, and Google Sites with good success. I generally make one page for each section that I would normally have in my requirements document. Just make sure you take advantage of the linking capability on a wiki that you don’t have in Word. You can also link to documents, spreadsheets, and diagrams.