If you are managing a team of business analysts or systems analyst you probably have two main goals in mind:
- to make sure your team understand the requirements (the real ones)
- to make sure that you develop a solution which makes sense in the context of your constraints.
The chances are that one of your biggest constraints is a current system. Few of us have the luxury of working on developing brand new systems starting with a clean slate.
Most of us need to be able satisfy the new requirements in the context of an existing system. But do you know what the current system does?
Do you know the “AS-IS” of your system?
At the core of the Agile manifesto is the call to value “working software over comprehensive documentation”.
I could not agree more!
After all – what good to anybody is the documentation if the software doesn’t work?
Unfortunately many proponents of Agile development tend to miss the fact that the agile manifesto does not say “no documentation”. Whether this is by mistake or by design, I don’t know.
But I do know that, as a business analyst or system analyst, decent documentation made my life much easier and saved my clients a ton of money.
Let’s assume for a second, that the software does work… and that whoever specified and implement the first version did such a great job that the software satisfies all the initial requirements.
But also assume that there’s not documentation!
Now you are hired as the next business systems analyst and are being tasked to help out with the development of version 2 of the software. You might be able to do a great job gathering the requirements but when it comes to specifying what needs to change about the system – you’re stuck! You don’t know what the system does… Yes – you can play with the current system and try to infer what it does but unfortunately the only documentation is “the code”.
Let’s be honest – the technical landscape is constantly changing and most business analysts (even the technical ones) do not have the time or the inclination to maintain enough development skills so that they would be able to navigate their way through a number of technical layers (databases & stored procedures, middle layers and services, web server code and client side-script, etc.) a variety of languages (SQL, C#, JavaScript, Java, etc.), as well as a mixture of architectural models (Client-server, SOA, n-tier, etc.)
You are now at the mercy of the developers – and hope that some of the ones which developed the first version are still around.
These types of environments are the ones where the developer is King. The analyst finds himself at the mercy of those who can read code and navigate the technical layers.
I am not advocating that, as a business analyst or system analyst, you do not increase your technical skills; I’m just saying that, unless you become a developer, you’ll need some level of system documentation to point you in the right direction.
As a rule of thumb here are a few project characteristics which would indicate that maintaining live system documenting might be advisable:
- the project is large (with a large team)
- the business domain is very complex
- analysis is done on-shore but the development is done off-shore
- the system is supposed to be in use for years to come (i.e. there will likely be lots of turnover in staff over the years)
- regulatory requirements exist which require certain level of system documentation (at least in the area of security, legal compliance, etc.)
- building services or components which will be re-used by other teams (the clients)
I will be the first to admit that maintaining decent (good enough) system documentation is not easy. In large teams and large projects you must have the commitment of the management (the folks with the money) to maintain system specifications.
I have worked on many a project where the initial set of documentation was quite good but as soon as the first “emergency” arose, exception was granted to code without specs which were supposed to be updated “later”. In such cases – “later” usually never comes.
Another must for your organization, if you’re going to maintain system specs, is guidelines and standards. Whatever level you decide to maintain your specs you must create and publish a set of standards for your documentation. This way everybody knows how to read it and how to keep it in synch with the code.
Do you maintain system documentation? Why or why not?