The Community Blog for Business Analysts

• 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?

Adrian