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.

Getting to expert: software learning skills

Picture of whole pie
Getting up to speed on 'Preferred' software experience can be as easy as pie (mmm...pie)

One of my fond memories of working in Finance MIS was a short-lived tradition called “Nerd Lunch.” I and another analyst would log in to a net meeting and work through complicated SQL queries every few weeks. We would brainstorm solutions for ongoing information problems facing our department. I ask you: Has there ever been a more appropriate moniker for an event?

The analyst was my guru. With her help, I went from landing a job where I knew next to nothing about the software I would be using to finding solutions for decision makers in our organization.

I’m writing this blog post because it’s great to get excited about a job posting that sounds perfect in terms of industry, position, and advancement opportunities – but then it’s disappointing to worry about qualifying on ‘Preferred’ software experience. Worrying about software experience may even keep a job seeker from pursuing a position. What follows are tips I’ve found helpful to first get through an interview without perfect software experience, and then to get up to speed quickly in software skills once hired.

For an interview: Likely you will be facing a hiring manager when answering questions about software skills. Before the interview, it is possible you may be able to fully investigate the software – say, with a free trial for more common products. Barring that, prior to sitting down with the hiring manager, I suggest Googling the software listed in the job posting to find its specifications, as well as those of competing software products. This is a particularly helpful step with specialized software, such as enterprise management, accounting or asset management software.

Investigate the capabilities of the software to understand the functionality, and then come up with (intelligent!) questions related to the software’s application to itemized job responsibilities in the position listing. After all, once you get the job, that will be your contribution to the organization. It is most important in an interview with a hiring manager to demonstrate understanding of the role and to express critical thinking skills related to a position’s responsibilities.

Once hired, read a book: Find a beginner’s guidebook to the software if you can. Also, read it. (NOTE: No one really thinks you are a dummy when you read those Dummies books.) Rather than buying it new, I suggest checking out,, or posting an ad on Freecycle for a used copy. I’ve always found that starting with these books gives a good comfort level for tinkering in the software, at which point you are ready to sandbox.

Sandboxing: This is when you’ll start breaking existing tools in a calculated way. Set up a dev environment for this step, whatever that may be. For tools that use scripts, like VBA, or query language, like SQL, pretty much everyone learns by stealing snippets from existing tools and modifying for new applications. This is the sort of stuff you can do while waiting on a batch of project work or during down times in cyclical reporting periods. Please do not underestimate the “Help” tool in a software package; these tools tend to get more useful as your grasp on the software jargon strengthens (ironically). There’s no shame in using company resources to iterate and build on your technical skills, particularly if you are the type to check Facebook or text during working hours.

Find a guru: A guru is different than a mentor. This is a person whose geek runs deep, but who has enough patience and time to answer your technical questions. A guru will also have excellent problem-solving skills, in that she (or he) can help you find answers to existing problems by walking you through previously applied solutions in the software tool. Surprisingly, perhaps, a real guru won’t do things like grab your mouse and make a quick fix; that person will have a conversation with you, explore the scope of the issue, and explain in plain language what you need to do. You will learn to deepen the relationship with increasingly thoughtful questions about the work at hand, eventually adding value instinctively. In the long run, a guru’s approach will ideally make you a better thinker.

When this person helps you, be sure to recognize her. Buy her coffee. Send a thank-you email to her boss. Write a blog post about her. Someday, if you care to, you’ll be in the position to act as a guru.

I hope this makes learning new software (or becoming an expert in familiar software) more attractive and less painful. The software is just a tool for the tasks at hand. In the end, you are the element adding value in the position, first by applying software and later by sharing your knowledge.

Photo by Caitlinator. Used in accordance with a Creative Commons 2.0 license.

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.