Documentation! …And I Don’t Mean System Documentation

documentation-0613We’ve all read about how important it is for us as integrators to provide good thorough documentation packages for clients on our integration projects. After all, we’re creating something custom and unique for them, and they need to know how it works. I’ve seen various document packages from several integrators, and they’re getting better and better as time goes on.

Why then, are the manufacturers going in the opposite direction? It seems that more and more lately, as new product starts shipping, that the technical documentation is weak or hard to access. I’ve spent the past several days working on a movie theater project for a local university. In this project, I had several newly released products that I was getting to integrate for the first time. There was a new projector series, a new generation of touch panel, a new surround decoder, even a new series of rack. Mind you, I work for a small shop, and I have the benefit of being the designer, engineer and programmer all in one. So I can’t blame anyone but myself for product selection. But who thought there’d be anything wrong? These were all just new products from tried and true manufacturers.

First off, there was the rack. Yeah I know what you’re thinking — “what documentation does a rack need?” How about what’s in the box? Nowhere in the sales literature did it say that it ships with rear rack rails. So of course, being thorough, I made sure to specify rear rack rails in the equipment list. When it arrived, not only were there rear rack rails included, but they were even already installed for me. Now I have an extra box of unneeded rear rails that I paid for, that now need to be returned. So I thought I’d go check the literature again. Nope, it wasn’t there. I went the extra step this time and downloaded and checked the detailed PDF. It wasn’t there in the list of features, but they did show up on the diagrams. Then again, so did other optional, a la carte components. So how was I to know what was included and what wasn’t? This was a fairly small headache, but one that could have been saved with a bit more detail on the manufacturer’s part, we could have saved the time, expense and extra shipping.

Now onto the projector:  This new beauty has one of those newfangled HDBaseT ports. Finally, I thought, “The vision of one-wire connectivity has been achieved!” We got it hooked up [to a different manufacturer’s transmitter] and fired up, and voila! A beautiful HD picture quickly showed up on the screen. The next step was to take control of this machine. The sales literature boasted of the built in support for a several manufacturer’s connection standards.  So I started sifting through information on the website of the control system vendor (I know better than to try to find tech details on projector manufacturers’ websites) and I found a white paper describing exactly this application. I thought I was all set! This article was divided into two parts, one part talking about setting it up if you didn’t need the projector to communicate with the outside world (thus saving an IP address), and the second part which was much more complex, which explained how to do it and still have it visible to the outside network (but at the expense of autoconfiguration of the control system). Since it didn’t need to see the outside world, and I wanted to save the IP address, I decided the first method was right for me. The problem here, is the white paper didn’t talk at all about what sort of IP settings to use on the projector. So I put in a call to tech support. First of all, it took some time to get the support agent to even find the document on their website that I was reading. Then he had me try some settings that contradicted the document. This was a rather complex process for reasons beyond the scope of this article. But after three hours on the phone trying different settings, reboots, trial and error, and level 2 escalation, we went with the second method in the white paper and things worked. I still am not convinced the first method wouldn’t have worked had there been a configuation example in the document. But I had wasted enough time on it.

Next was the touch panel. This was my first chance to get my hands on this new series of panel. I will admit, that I did not go to a detailed training session on this, so part of this is my own fault. I did watch some intro videos, so I felt confident enough with the workflow and figured that whenever I got stuck, I’ll just hit F1 and it’ll explain the detail. So I set out to do the touch panel design using the new toolchain. While I was very pleased to see all the new power of the new tools and design elements, I was confronted with myriad new settings with names that were’t very self evident. I hit my trusty F1, and got nothing. It did open the help file and took me to a generic page telling me about the new toolchain. But no matter how much I searched, I couldn’t find any chart explaining what these settings actually did. For this manufacturer, this is a real departure from the past. They always used to be very good with documentation. The style may have varied widely, but it was always there, and in fairly good detail.  Some of their oldest stuff even included examples right in the help files. Now I was left with two options, tech support, and trial and error. I ended up using a combination of both to get the job done. There were a few instances where a call to tech support would yield a support agent paging thru the same documents I had already read and he was no more educated than I was.

In the end, I did get the project completed successfully. And it was very nicely done. The rack looks beautiful. There’s only one wire going to the projector. The new touch panel looks beautiful and is super responsive. On the other hand, I think I spent about 16 or so hours on this project more than I planned. I suppose this is still less than going to a handful of training courses on non-billable time. But that 16 hours probably could have been trimmed down to four or so if the necessary technical resources actually existed and were available in a usable form. There are people who read those books, and it’s us: the integrators, designers and programmers. A new fancy product with new features is useless if we can’t figure out how to use it. Please keep those documents coming, and make sure they’re available when the product is in our hands!

Jon Chuchla is a blogger for rAVe [Publications].