This blog covers the practical techniques, trials and tribulations associated with the transformation of IT systems from legacy technologies to systems using SOA and modern open systems. It also includes the occasional interlude with rants about technology in general.

Friday, July 23, 2010

On Documentation

One of my biggest professional upsets took place when, as a young programmer, I lost weeks-worth of documentation I had diligently created for a bank settlement system I had just finished coding. I had entered the documentation via a vanilla text editor (those were the days before modern word processors!) and, sadly, I had neglected to follow proper backup procedures. I had no versioning or backups as I was always saving my file under the same name (I was young, remember!). A fateful evening, just as I prepared to leave work, I pressed the Return key to save my nearly finished document back to disk. Literally, at the precise moment that the disk’s red light began to blink, indicating the save to disk was taking place, the office experienced a brief electrical brownout. It was an outage that left me with a corrupt file, my extensive documentation gone, and with fits of cries and cursing.

Other work priorities and accelerating deadlines prevented me from redoing the document with the gusto and detail I had invested in it originally. Upon delivery of the system, I went with a quick cheat-sheet that summarized the workings of the system and then I verbally explained to the users the key features and manner of use of my application. In the end, the customer was so satisfied than it dawned on me that the long lost documentation was never even really been needed!

Still, internally I was disappointed. I had a sense of missing the complete deliverable and even to this day I imagine how cool and grandiose my eighty page documentation manual would have looked sitting next to the eight and a half inch floppies containing my code. In time, though, I became grateful for this twist of fate. As I proceeded to improve upon and change the system, I realized that that original documentation stack would have been extremely cumbersome to maintain, and that with each successive new release would have become promptly outdated. In the end, the system worked so well and lasted so long that it never did require those eighty missing pages of documentation.

Keep in mind that my experience preceded those Apple Mac commercials from the mid eighties bragging about how skimpy their manual was compared to the PC’s. I was an accidental pioneer in the school of thought that says ‘when it comes to documenting, less is more’. This view on documentation is now common. Nowadays, getting software with documentation is as rare as getting more than one bag of peanuts on a commercial flight.

The trend towards less documentation is only viable as long as you define and design the system with usability in mind. Creating a complex and cumbersome system and then trying to deliver it with no documentation is a sure ticket to perennial support hell. Fact is that some documentation is always needed, but even when documentation is required you can now avoid paper manuals. That era is long gone. Focus instead on creating electronic files using modern collaboration systems. The best systems are self-documenting in each of their layers. When it comes to source code, for example, ensure that programmers follow best coding practices and the automated documentation facilities provided by the programming language you’ve decided to use. The wealth of material created during the analysis of requirements phase, as well as in day to day communications (emails, file transfers, etc), regarding definition of features and functionality can also be seen as living documentation. Make sure this information is never lost in the limbo of disorganized mailboxes of the team, but is instead properly indexed, catalogued, kept, and propagated via Wikis, so that it is always available via a web portal to the appropriate users.

Ultimately, the online help screens, combined with the various Powerpoint presentations used for presentations to executives and the team plus demos and training materials, will constitute the core documentation for your system. Systems that are easy to use, capable of self-diagnosis and auto-recovery from exceptions, and that provide comprehensive and understandable status information need not rely on bulky external technical documentation. This is particularly true in the realm of SOA; where systems should naturally mirror the business processes they implement.

Beware of project plans with a standalone task for “System Documentation”. Documentation should be an organic element in the design and development process; not a separate task. If anything, the company’s business process documentation should serve as a suitable reference. Ultimately, the best documentation is an intrinsic part of the deliverable; not a fat manual collecting dust in a corner cabinet.

IT Transformation with SOA

About Me

Israel has been recognized by Computerworld as one of their Premiere 100 IT honorees. Israel is a business and technology leader who has contributed the technology vision as key strategist and designer behind the enterprise technology roadmaps of large hospitality and travel companies. Israel has also have developed and deployed various mission-critical systems and in the process, he's been instrumental in creating and building effective and skilled development organizations.