The Elephant and the Blind Men

Thanks V for emailing me another link to an off-the-mark Documentum blog at 01:30 and keeping me up all night.

Blogs about Documentum are popping up all over the place. Some suffer from a myopia based on limited experience with a complex product. Virtual documents are not categorically evil. Documentum back-ending SAP isn’t a good example of anything other than marketing-driven hackery. A Java programmer can’t “learn Documentum” in 21 days.

Documentum is big, really big, Carl Sagan billions-and-billions big. There are several dozen different software components on top of a hybrid object database and content storage system. That object database comes with an incredibly rich schema that has evolved over many years. It carries plenty of junk DNA. Early versions included minimal clients; customization was essential for even basic functionality. In fact Webtop, the client du jour, was a reference implementation that borrowed some very corrupt interaction design DNA from its predecessor, Rightsite. Documentum is getting old and can’t reinvent itself at the core because of all those bloated docbases holding the company jewels.

One point bears repeating. The Documentum server is a much more complex information system than a database server like Oracle because it’s not tabula rasa out of the box. It comes with a vast collection of object types and tables that relate in obscure ways on top of its database server capabilities. Its genome bears the DNA of plenty of evolutionary dead ends like the unix-based security system and the original compound document–a version 1 precursor to the virtual document, not a virtual document mimicking another structure like XML or OLE linking.

The very idea of finding content on the internet about Documentum is still hard for me to comprehend. In its first decade, the company jealously guarded information about its product and actively discouraged third parties from writing books. Now V sometimes tortures me by sending links to the worst posts. Maybe the silver lining in Documentum’s third party blackout was me getting to bed earlier. But I digress.

I have the same problem talking to new developers all the time. They describe Documentum in the language of their technological comfort zone: A database guy will talk to me about tables and queries. A web guy will talk to me about application servers and the web content management lifecycle. A java programmer speaks in DFC with little understanding of what lies beneath.

It doesn’t help when their words have one meaning in their comfort zone and another in Documentum. That even happens across Documentum versions or components. It got so bad that Documentum started including a glossary in the documentation that maps one version’s po-TAY-toe to another’s po-TAT-oh. Honestly, I’m at the point where I pick the name I like and stick with it especially when a real stinker is in vogue like DocPage Server. Bleh!

It’s the Documentum retelling of the Story of the Blind Men and an Elephant. People with a few years of experience use a few tools, not the entire toolbox, to solve a few very particular problems. What makes this worse is clients aren’t trying to solve interesting or novel problems anymore. One reason is the product’s popular enough that clients have preconceived notions about what Documentum can do. Another is EMC (and Documentum before it) trying to open up new markets. Anybody else remember the fiasco when Documentum decided it was a web content management system and snubbed pharma and aerospace? Not good for anybody.

Contractors fare a little better than full-time employees because they see more projects and get faster access to new versions by hopping to new clients who are Documentum first-timers. Even contractors can get bogged down though, getting typecast by technology or industry and only working those kinds of projects or clients. Maybe the nature of the business works against knowing the entire product unless you make it a priority.

It’s also possible that the whole thing is just too big to grok. I certainly don’t know the entire suite of the top two versions in spite of concentrating on Documentum for 14 years now. So how’s a reputable developer or blogger supposed to see the entire elephant? Step back and look at the whole before focusing on any one component.

Ok, I’m biased. I’m a server programmer turned architect so my approach will probably drive java purists crazy. They might argue that if the DFC is a complete abstraction of the system, it would provide a conceptually integral view of structure and behavior while concealing the hackery and junk DNA at the lowest levels. Studying the guts would be more confusing and likely to lead newbies down dead ends.

The problem is that the DFC (at least up to 5.3) doesn’t completely cover the system and is still poorly documented–especially given how long it’s been in use. I still keep the Object and API Reference Guides close at hand when doing DFC for when the javadoc map is blank and the code does something unexpected–and it always does. Our web-enabled cut-and-paste programming culture probably isn’t helping. And yes, I do it too. Damned internet!

Although I’m warming to Java (after more than half a decade), I still think it’s a cumbersome language that can bury unskilled programmers in a mess of abstraction and layering. A first year computer science undergrad should still start with C. Any other science starts with the fundamentals and builds upon them. C is a terse language that sits closer to the hardware; it makes for a difficult but instructive experience by getting closer to how the computer actually works. It’s high-level enough to escape the disconnect from reality that comes from doing assembler–similar to how quantum physics makes no instinctive sense to monkeys evolved in a macroscopic context. It’s also good to know a little about the byte shuffling underneath for when things go wrong. Introduce Java after C and let the student’s understanding evolve just as the languages did, one from the other. But I digress again.

So here’s how I recommend getting to know Documentum better:

• Study the Architecture Overview document until you can draw the system architecture from memory. It will help you intuit where something happens, especially when something goes wrong.
• Read Server Fundamentals at least one time all the way through and skim the Administrator’s Guide. The server is the foundation upon which everything is built; these documents provide an overview of the system’s base structure and behavior.
• Keep the Object and API Reference Guides handy. When something unexpected happens, look at the model to get a feel of what objects are involved. The API guide can provide some history and particulars hidden or ignored by the DFC or the javadocs. Oh, and print out that giant E-R diagram if you have a plotter.
• Get comfortable with IDQL and IAPI (or one of those swiss army knife tools although it feels like cheating to an old timer like me) so you can examine the underlying state while manipulating it at higher levels (DFC, Webtop, etc.)
• Run IDQL, IAPI, and scripts on the docbase server’s host to cut out any caching annoyances and docbroker switcheroos. Unix geeks, feel free to tail logs too.