Tuesday, June 07, 2011

If you didn't write it down, it didn't happen!


We've all been there. It's crunch time. Where did the time go? Weeks of requirement gathering, architecture, development, unit test, integration test, and now go-live with a whole bunch of dependencies and C-level attention is right on top of us.  There's only time to address the last minute issues.

Throughout the project, the PM has been screaming for documentation.  Where's the completed architecture  Where's the test plan that you said you worked against? How about a run-book? And on, and on and on...

Too many architects, leads and engineers regard documentation as a necessary evil at best. Until it comes time that YOU are the one inheriting the project and YOU have to try and understand what some guy did in the past.  If you're really lucky, you know the guy or he's still with the client, or maybe even your practice if you're a consultant.

We all seem to forget that documentation is just as important as any piece of code, fancy database query or complex workflow.  It's the basis for the whole project.  It needs to be focused on just as much as any piece of development or testing.

The fact is, if you have a good design, any engineer can build the solution.  If you have a good test plan, the QA meeting flies right by and the change control board meeting becomes a coffee break rather than a Homeric battle to prove that your solution is up to snuff.

It also benefits you as an architect/engineer/consultant.  If it's written down, it's easy to reference for future work.  Remember, when you're sitting in the corner office as the CIO and someone comes up to ask you "back when you were the IDM lead, how did we do ... ?"  Well if it's written down, you'll know!


What ticks me off even more, is that it's SO easy to create even basic documentation in NetWeaver IDM. Fill in the documentation tab for tasks and folders with a few notes, references and examples. Put some comments in your scripts and then run the system report.  The most you might have to do is install the MMC console on your desktop so that you have access to Office. Then just run a bare bones system report.  Voila!

Just in case you haven't figured it out, I have inherited Phase II of a project with sparse technical documentation and everyone involved in this Phase is paying for it. In reality this is seldom any one person's fault.  There's limited time and multiple pressures as I mentioned in the opening of this essay, however that needs to stop being the excuse.

Based on the lack of documentation created in the past, there's increased attention on design and architecture documents, so at least the lesson has been learned in this situation.

It sure would have been easier to write if there was even some documentation.  Now I'm living in a world where nothing was written down, so I don't know what happened!
Post a Comment