How much documentation do you need?

Stacks of documents being measured with a tape measure
Used under a Creative Commons License courtesy of gadl @ Flickr

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.


On Adding Value in an Organization

There are obvious ways to add value to an organization: productivity by salespeople is generally measured by number of units sold, or levels of service contracted with clients. These quantities show a direct impact in organizational revenue.

The greatest challenge to a new Information Manager (IM) is demonstrating the added value of his work; an IM is a cost to an organization, not a revenue center. Adding to the difficulty, an IM has a wide range of constituents within an organization – such as finance, marketing, and lines of business – meaning he must translate his value add in a variety of operational environments.

For these reasons, it is essential that an IM compose a value-add statement for each project or process improvement. A concise value-add statement with the following points will help to focus a project or process improvement effort from start to finish:

The Impact. Give ‘before’ and ‘after’ statements for the project. The ‘before’ state should be plainly articulated and based in facts. It should also be no longer than one sentence. The ‘after’ statement represents the ideal outcome.

Information Need. Based on the ‘before’ statement, the IM should indicate whether the information is known to exist. Issues with existing information, such as redundancies or gaps, should also be noted here.

Stakeholders. There are two important aspects to this point. First, identifying the right stakeholders will ensure buy-in and participation from the project team. Second, limiting the scope of work and executing rapid iterations of the solution will be easier if stakeholders include only relevant and affected parties.

Revenue or Cost Result. Cutting costs generally means eliminating redundancies. Really exciting projects – the challenging ones requiring an IM to delve into and learn a line of business – should enhance or protect revenue streams. An IM who is able to quantify the financial impact of a project will be better prepared to assist a line of business in process enhancements.

The outline above seems overly simple, but there are several advantages to putting this short document in order. First, the IM may look to the value add statement for guidance when a project threatens to grow to an unmanageable scope. This is essential when working at an organization without established development or process improvement methodologies (such as Agile or Six Sigma). In addition, the exercise of articulating a project in the above terms will assist in communicating casually with senior managers and potential stakeholders for future projects (“What are you currently working on?” asked in the elevator). Finally – what is good for the organization and the project is also good for an IM’s professional development. Annual reviews are an ideal opportunity to review past value-add statements; these documents can also be helpful for updating one’s resume.

If there are any points for a value-add statement I have forgotten above, please let me know in the comments.