[This entry is lifted verbatim from a message I recently wrote in email to a good friend. We were idly discussing a bit of documentation that one of his technical writers had produced, when he commented that he created his own standards: whatever he said, so it would go. He concluded, “It’s good to be the king, sort of…”]

I was lapsing into the way things used to be. Once upon a time there were Standards for everything.

Here’s a funny story. There’s no real proprietary stuff here, but it sheds a teeny tiny bit of light on the seedy underbelly of a company that would probably prefer otherwise.

Back in the 80s and before, there was a Standards Department. A handful of folks: a few writers, a few managers, a room of shelves with binders. (This was, of course, pre-LAN, pre-email, pre-all-the-stuff-we-take-for-granted-today. They walked floppies to a PC that was connected to an IBM line-printer. This was modern; not much earlier they used typewriters. The IBM ball-headed devices – were they called Quietwriters?  Selectrics – were still around.)

I hear you saying, “roomful of shelves with binders? Golly, what could they be documenting?”

Back then, every system, every subsystem, every sub-subsystem, every database, every data feed, every EVERYTHING was custom-built for a specific purpose – be it another system, a customer, whatever. This was before all the wonderful acronym-laden standards for such stuff we have today. (“I love standards – there are so many to choose from!”)

Anyway, time passes and in comes LANs and email and all kinds of magic and, one day, they went and dissolved the Standards Department. Figured that the Programmers could write their own documentation. Out went the writers, one by one. Then the managers. Their equipment was collected and taken away and their space was re-allocated. But not before I scoured their PCs for their documentation files. Thousands and thousands of Word docs. Stashed ’em away in a big zipfile, I did.

Then there was the room full of shelves of binders. A girl I knew, a minor manager, was given the mandate to keep the lights on.

So the years passed. Major systems were rearchitected to common standards. New products were created. The outsourcing wave washed upon the tech shores. And lots of old talent – along with the knowledge of how the proprietary systems worked – was shown the door.

Along came Y2K, at first just a glimmer on the horizon. With the massive technical audit that was undertaken to prepare for that event came the realization that quite a bit of the shiny, new, “self-documented” code was critically dependent upon… wait for it… bits of old legacy stuff that nobody knew anything about anymore.

“Wait!” someone said, “We’ll call the Standards Department! All this stuff is documented!”

Uh oh.

It took a while, but eventually it was realized that the Standards Department had been decimated the better part of two decades earlier. Some hand-wringing later they discovered the roomful of shelves of binders. It had been dutifully passed along from hand to hand through several reorganizations, relocated over 2-3 facilities moves, but there they were. Unmaintained. Disorganized. Dusty. Thick, blue, three-ring binders, labeled with crusty, cryptic strings of numbers and letters – if you were lucky. Some had fallen off with age. But descend upon the room they did, borrowing one volume or another as the analysis plodded onward.

I remembered the original room, the old Standards Department, and when I heard about this I smiled. But when I heard that as often as not the borrowed volumes weren’t being returned, my smile turned into a frown. I grabbed control of the room, had it locked, began to mediate access. Soon I was doing a brisk side business as a librarian. I blew the dust off the forgotten zipfile and got the content onto the network. After all, it’s way easier to content-search a tree of files than to traipse over to some other building an spend hours with those dusty old binders. Or sign your life away to the shaved-head dweeb that made sure you brought ’em back. Trouble is, the files and the binders ain’t exactly one and the same all the time.

And then, there’s the stuff that no one, try as they might, could find documented ANYWHERE. Several thousands of those entities were scattered across the organization. Little black boxes, you can see what goes in and comes out, but haven’t got an inkling of what goes on inside. Except when one little black box talks directly to or from another little black box, hmmm, then you don’t really know much about the interfaces either. Quite troubling.

Y2K came and went – rather uneventfully, actually. The world didn’t end. The systems actually came out the other side better than they went in. Life went on. Interest in the room and the files waned, but didn’t go away. As it turns out, Programmers, especially contractors, especially hourly contractors with lots of churn, aren’t exactly the best when it comes to documenting their work. And “self-documenting code” really isn’t, unless the reader is quite technical. The legacy stuff, well, the stuff that’s actually documented, turns out to be the best documented stuff there is. Created by people whose job it was to make it so.

Now here’s the punchline. To this very day, if you dig deep enough, through the shiny, new Web-enabled, SOAPed and serviced layers, you could very well discover dependencies upon some bit of legacy code or another that *nobody* understands, code for which there’s *no* source code, *no* documentation…

This is a good time to end the story, as we sit and sip our morning coffee, pondering the sinking feeling in the pit of the stomach of some poor sod somewhere whose unfortunate lot puts them near one of those bits of code.