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.

Advertisements

Lessons Learned on Design, Analysis, and Agile

Sticky notes clustered together for an agile planning meeting

When I was at InfoCamp a couple weeks ago, Erin Hawk and Samantha Starmer both spoke about how they’re working to integrate design into the Agile Software Development process.  This got me thinking about some of the successes and failures I’ve seen in Agile projects and how those related back to the integration of the analyst role into those projects.

Since Agile was a methodology created by developers for developers, it tends to be fairly development centric, and a lot of Agile implementations neglect both design and requirements processes.  As someone who has been in the development, analysis, and design roles of systems implementations, I have seen Agile applied with a variety of results.  Overall, the projects that successfully integrated designers and analysts into the Agile process tended to have much better results.

Many projects are unsuitable for developers to be the primary group interacting with stakeholders (that’s another post altogether).  Integrating designers and analysts into an Agile project helps ensure that the end product meets both business and user needs the first time (ie; on time & on spec). Not to mention, it makes the developer’s job easier by cutting through a lot of the ambiguity around a project and reducing the number of times developers will have to change what they’ve made.  Unfortunately, since Agile stresses speed and iteration over carefully planned designs, it’s not necessarily easy to integrate that into the process.

Here are four of the lessons I’ve learned on how to succeed in Agile development from an analyst’s point of view.

1 – Be an agile waterfall

Agile development focuses on rapidly developing, testing, and releasing a product, which has a tendency to squeeze out designers and analysts . However, many projects and products are so complex, and have so many stakeholders, they require specialists (aka designers & analysts) to handle that complexity.

The best Agile projects I’ve worked on keep all of the phases of the Systems Development Life Cycle, but compressed them down into small and fast chunks.   By reducing the project into a cluster of discrete but related deliverables, ie; user stories, you can keep all the phases of the SDLC but still move at a rapid, iterative pace.

2 – Use staggered phases to keep designers & analysts ahead of developers

One of main reasons that Agile has gained so much popularity is that developers and organizations became fed up with lengthy requirements gathering and design processes.  Such processes tend to lead to specs that are out of date by the time the developers get around to them.

By having designers and analysts work one phase (or two phases at most) ahead of the developers, organizations can deliver just-in-time specifications.  Ideally, the development team can put together a rough set of initial stories and prioritize work accordingly at the beginning of the project.  After that, an initial sprint (called sprint zero by some) can give the designers and analysts time to get ahead of the developers while they set up dev environments and take care of any other start up items they have.  Sprint length will vary from organization to organization, but in my experience two weeks is a good length of time for each group to do a thorough job with their current tasks.

3 – Coordination & communication is key

I can’t stress enough that everybody needs to be in constant communication throughout the process.  As analysts are working on requirements, they should be giving developers a heads up on what’s coming down the pipe.  This keeps the developers abreast of changes, and there will always be changes.  While developers are programming a current set of tasks, analysts can provide feedback and integrate any changes the developers want back into the requirements documents.  A good project manager is often key to this process, as project managers are skilled at keeping up communications and preventing the geeks from siloing up.

4 – You’re either all-in or you’re all-out

Either everybody is working on the project, or nobody should be working on the project.  One of the biggest wastes of time  is when development resources get pulled from a project, but the analysts and designers keep going.  In the best of cases it takes 6 months for the developers to come back, and keeping the rest of the team on the project will lead to a waterfall style mountain of  obsolete design documents.  In the worst case, the project gets cancelled, resulting in wasted effort by the design and analysis teams. If one team gets pulled from the project, management should sideline the project until everyone can get back to it.

Those are my 2 cents on the matter, and I’d love to hear about your experiences in integrating design and analysis into Agile projects.