The Community Blog for Business Analysts

Adrian M.
Adrian M.

The Case for System Documentation aka "Developer Is No Longer King"

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?


This entry was published on Jan 14, 2015 / Adrian M.. Posted in Systems Analysis, Leadership & Management, Agile Methods. Bookmark the Permalink or E-mail it to a friend.
Like this article:
  31 members liked this article

Related Articles


Only registered users may post comments.

Modern Analyst Blog Latests

As we start a new year many of us will take the time to reflect on our accomplishments from 2012 and plan our goals for 2013. We can set small or large goals. goals that will be accomplished quickly or could take several years. For 2013, I think Business Analysts should look to go beyond our traditional boundaries and set audacious goals. Merriam-...
Recently, I was asked by the IIBA to present a talk at one of their chapter meetings. I am reprinting here my response to that invitation in the hope that it will begin a conversation with fellow EEPs and BAs about an area of great concern to the profession. Hi xx …. Regarding the IIBA talk, there is another issue that I am considering. It's p...
Continuing the ABC series for Business Analysts, Howard Podeswa created the next installment titled "BA ABCs: “C” is for Class Diagram" as an article rather than a blog post. You can find the article here: BA ABCs: “C” is for Class Diagram Here are the previous two posts: BA ABCs: “A” is for Activity Diagram BA ABCs: “B” is for BPMN


Blog Information

» What is the Community Blog and what are the Benefits of Contributing?

» Review our Blog Posting Guidelines.

» I am looking for the original Modern Analyst blog posts.


Copyright 2006-2024 by Modern Analyst Media LLC