Tuesday, April 28, 2009

Misguided documentation

Documentation is one thing in software development which no one wants to do and hence gets talked about too little or, gets talked about a lot and still no one wants to do it. Even if documentation exists its a pain to read or get at the information that you want mostly because of bad abstracts and introductions. With the proliferation of software methodologies each requiring its own type of documentation its a mess (just like the code :P..). Even in a single methodology there are approach documents, HLDs, LLDs, use-case documents etc. most of which are sometimes not very relevant but, since the the enterprise processes demand it they are still produced and maintained :O.

I had to pick up the implementation of a small (er. tiny actually) feature and was given 2 documents to start off. The first was an abridged requirement specification covering just the change that I was supposed to do and the other an impact analysis document. The requirements document was pretty straight forward (except for some vague clauses added just so that the business analysts can bargain later). The impact analysis document was quite another beast, over 20 pages long (excluding the fluff like cover sheet, intended audience, disclaimer etc.) it was a carefully copy-pasted creation that discussed the same approach that was to be implemented in about 7 use-cases. If you were looking for existing functionality, use-cases impacted, use-cases that should not be affected, alternate flows, expected areas of conflict with previous changes etc. this was not the document to read. All the document said was in such-n'-such a screen, a field should be added the corresponding back-end code should be invoked blah blah for every use-case. I see absolutely no point in maintaining a totally worthless project artifact like this. If a change requires just a specification and LLD why not leave it at that why go through all the hoopla of creating all other worthless documents?

No comments: