Product Documentation

Product Documentation

By Ernest Robl

 

In several forum threads, members have complained about the quality of documentation of the Roco Z21 system – while endorsing the product itself. I don’t have that system myself. I use the Roco Multimaus, the documentation for which is not that bad, but not really great.

But, having worked in the field of technical documentation, I can offer some thoughts about documentation in general. Good technical documentation is not easy to produce. It requires understanding of both the product/process being documented and, most importantly, the needs and interests of the user.

It’s in the latter area that much model railroad technical documentation falls short.

Let me provide an example. In the 1990s, I worked for several years for a company producing a computer-based system for managing international freight shipments. I was in charge of the user documentation. A big problem was that we were documenting a constantly changing product. The software was continually being developed up to each release date.

But, one of my major problems was that the other people on my team – two writers and an editor – had no real understanding of, nor interests in the finer points of international trade. While my interests in transportation had always focused on railroads, along the way I had picked up enough background in a variety of other forms of transportation, too.

And, I’ve always been a naturally curious person, wanting to know how and why everything worked.

The people who worked with me were perfectly competent writers. But they had a really tough time understanding what the users of this system would be doing with it. One example was that our editor, whose primary job was to proofread and to correct spelling and grammar, kept changing terminology, mostly without asking me.

She kept telling me that I had used certain words too many times in the same paragraph. I don’t think I ever convinced her that in the transportation/logistics business, certain words had very specific meanings – and that you could not simply substitute other similar terms.

And, this software was going to be used by people around the world, many of whom would have English as a second or third language. We were not trying to write elegant essays, showing off our literary skills. We were trying to help these people do their jobs.

I think that the problem is that, while many technical model railroading products are developed by people with a strong interest in model railroading themselves, the documentation is contracted out to professional technical writers, who may have just finished writing instructions for a toaster oven or washing machine. (And, the latter are actually easier, as most people have at least some familiarity with these household appliances.)

I could write lots more on this subject – and probably bore everyone in the process.

I’ll just mention that, though I have been interested in model trains for most of the past half century, as of two years ago, I had zero engines with decoders, today I have 12, as well as a cab control car, which also has a decoder installed. A couple of used engines were bought with decoders; the rest I installed myself. All of the decoders required at least some programming.

So, as with most everyone else, digital model railroading has involved a learning curve.

I won’t list all the bad documentation I’ve found along the way. But, I do want to mention that the instructions for the Viessmann 5244/5245 locomotive decoders were among the best I’ve seen. They are well organized and have just enough illustrations.

These decoders are not among the smallest, but should fit into most HO locomotives which already have a space intended for a decoder

##########EHR##########

 

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>