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.


6 thoughts on “How much documentation do you need?

  1. Great points made!

    Having struggled as an intern trying to create meaningful documentation for my projects, it was educational for me to realize how difficult it was to answer “Who will read this documentation, and how will they use it?”.

    Thanks for the commentary! Most discussions around documentation seems to be about specifications rather than process.

    1. Nick Malone says:

      Answering the question of “who am I writing this for?” can be difficult sometimes. However, if you can’t answer it, that may be a red flag. In my opinion, being unable to answer that question can be a sign that you’re writing documentation for the bureaucracy and not to meet any particular need. Documentation for the bureaucracy is whole other topic.

  2. Jordan Eschler says:

    Nick, I think retaining a combination of documentation sets available to other stakeholder groups for the benefit of future analysts, in and of itself, is a valuable process. As someone who has been the “future” analyst (analyst of the future?), I’ve been the grateful recipient of a binder that included all of these artifacts.

    Sometimes, learning that the other stakeholder groups are not bothering to use past documentation can help with identifying existing workarounds from the last system build/update. (I also used to ask for any informal documentation the users had, which sometimes consisted of a page of handwritten instructions, or an e-mail archived for reference.)

    This is my favorite post of yours so far!

    1. Nick Malone says:

      Thanks! Keeping an archive for analysts is a great idea. There are times that I would kill to have all the documentation I need in one place. Figuring how to keep it is the hard part. I’ve never seen the binder archive in action, but it sounds like it might be more findable than some of the electronic “archives” out there. I almost always have to resort asking someone where to look.
      Also, I’ve decided I want my next job title to be “Analyst of the Future”

  3. Yunju says:

    I wonder if you only have limited time to write one spec for all users: client, UI designer, engineer, tester. How would that work? As detailed as you can get and let everyone digest by themselves?

    1. Nick Malone says:

      My opinion is coming from someone inside an internal dev organization and not an agency, but I think the one document for all approach doesn’t work very well. It can almost never meet everyone’s needs, and it will probably take longer to write one super document than 2 – 4 smaller documents.

      Specs for engineers and testers can be combined if designs are concrete before development begins, but if you’re changing designs during development, test documentation can’t be finalized until afterward. Same with user guides, they might not be accurate if they’re written before development completes. There are probably situations where the technical documentation is useful to the clients such as consulting for someone’s IT department,but it would just be confusing if your clients are internal stakeholders like the marketing or sales department.

      In my opinion, it’s a better idea to write what’s need now. Then come back later and write more documentation as it’s need. Just-In-Time documentation. In the long run, it will save you time. Here’s a good article on the topic:

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s