As a business systems analyst, one of things I struggle with is finding the right balance of documentation. Often times documentation feels like a chore and as Modern Analyst points out, it can seem downright counter-productive in an Agile environment. Yet, in many situations documentation is necessary for other project stakeholders to do their jobs and to ensure that someone can learn how the system works once you’re gone. The tricky part is finding out how much and what type of documentation is required.
Probably the most important consideration when determining documentation efforts is to consider your stakeholders. Who will read this documentation, and how will they use it? Here are a couple thoughts on how different stakeholders use documentation and descriptions of their unique needs.
Software Developers: If the main users of your documentation are going to be software developers, you might as well not write it. I kid, but seriously developers do not really need detailed specification documentation, and generally won’t read it anyway. In my experience the best types of documentation for conveying business requirements and rules to developers are simple artifacts like wireframes and flow charts. Those, along with a handful of conversations and some white board time, are generally all you need to get developers building to spec.
Testers: The underpaid, understaffed, and underappreciated grunts of the software world ensure that our software works in all those edge cases and produces predictable results. It’s been my experience that these guys and gals often need highly detailed documentation to get the job done. Detailed documentation gives them specific details they need to write test cases with predictable outcomes. Furthermore, testers are often located offshore, complicating direct communication and making detailed documentation all the more necessary.
Business Users: When process owners change, aside from wanting to scrap the entire process, the new owners will generally want some documentation that explains both the purpose of the business processes and how the software work. Ideally, process owners and business stakeholders can provide much of their own documentation. To meet these needs, a business case can explain the purpose and goals of the process/system, and some operating procedures or guidelines will provide an overview of the business process. Finally, the analyst might want to provide a flow chart and some notes explaining how the process and system fit together, along with appropriate references to the more detailed documentation if it exists.
Future Analysts: Often times, I have found myself cursing the people who left behind no documentation on the workings of the system I am expected to modify. Don’t be that guy. When reading historical documentation, analysts mostly need to be able to glean business rules, the project justification, and some idea of system processes from documentation. These can generally be derived from some combination of the other types of documentation listed above. As long as the other documents can cover those subjects, there probably is not a need for documentation specifically intended for future analysts.
Unfortunately, each set of stakeholders requires a different type of documentation. Sometimes this means that we analysts need to write multiple sets of documentation for the same project. In the end, analysts should aim for just enough documentation get projects accurately built and tested, and enough documentation to ensure future stakeholders can understand what was done.
If you’re interested in more on this subject, Modern Analyst has a great article on requirements specification in an Agile environment that touches on this, as well as recommendations for methods to communicate requirements.
Discussing how to manage your information 