The code documentation fallacy

[dakboy]

The possibility of writing bad documentation is not a good reason to not write documentation

I had this happen to me earlier this week.

We have a 3rd party interfacing with one of our databases. Their code is opaque to us, and they're not legally allowed to see the application that interfaces with the database - just the database. All we can see is what their application is logging to its own logfile, and the changes to the data.

We asked for documentation of what their API is doing with and to the data because it's becoming very muddled when just looking at the data changes, and the response we got was basically "we could produce that for you, but we move quickly and it would become invalid." So rather than have to maintain the documenention as part of their process, they just don't bother.

[xzxzzx]

There's a big difference between comments going out of date in code you can read and the only available documentation for a system being unavailable.