Phil Wainewright posted one of the IT commandments today: Thou shalt document all thy works. This is a perfect followup to my post yesterday about SOA and data, although it may not appear obvious at first. Problem: application developers don’t use services when they should; in yesterday’s post, I was talking about how they squirrel away data in their own application-specific silos, but the real issue is more widespread than that. Wainewright hits it on the head:
Failure to document is thus one of the biggies of ZDNet’s IT Commandments, high up in the mortal sin rankings with the likes of ‘Thou shalt not kill’. For if you don’t document your work, how is anyone else supposed to reuse any of it? From your greater sin flows a multitude of others’ lesser transgressions.
In addition to yesterday’s more easily defeated arguments that developers don’t use services because the data may not be accurate or it make take too long, we add this one that’s harder to counter: the developers don’t use services because they’re not properly documented. This is often blamed on developers having a “not invented here” attitude, and wanting to build everything themselves, but I disagree (in general).
I’ve been a developer, and I used anything available to me as long as I understood how to use it, how it worked, and its limitations. In other words, I used third-party code/services if they were properly documented, and I could determine from that documentation that they suited my needs. If they weren’t documented and I had to walk through the code (if that was even available) to figure out how it worked, then I was more likely to just rewrite it myself, on the basis that if someone couldn’t write proper documentation then maybe they couldn’t write proper code either. Later, when I ran a development team, I made the developers write the documentation first. They bitched about it, but we had a high level of code reuse.
There is no way to achieve SOA without reusable services, and there is no way to achieve reusable services without proper documentation of those services.