Does Documentation Matter for a Product?

How important is the documentation (manual, user guide, instruction booklet) for the actual quality and perceived quality of a product? Does it materially affect the user?  I was recently confronted by this question is a very direct way.  It turned out that the manual for our new car was not quite what you would expect…

This is just the first page, and as you can see if you know Swedish or German or both, it is a strange interleaving of sentences in the two languages.

It is not the rather common “repeat the same thing in multiple languages” model.  This is a single coherent flow of text that just happens to alternate between two different languages. Amazing. Here is an annotated version of the same, showing the languages for each paragraph:

Confronted with this mixed word salad, two questions are immediately raised:

• How on earth did this happen?
• Does this have any implications for the quality of the car itself? If someone is this careless with the documentation, what else is wrong?

How?

On the first question, it is rather unbelievable that a huge international car company can put this kind of misch-masch into the hands of an actual customer. Didn’t anyone even look at it before it was shipped? Where was the proof reader? Or is this the result of some complicated book publishing system that managed to mix up two independent versions of the same text? Questions I will probably never know the answer to. I did call the dealer, and they told me that yes they were aware of the issue and that new manuals were being produced.

Before I move on, I have share another example from the manual:

German text highlighted in yellow. We see the language being switched in the middle of a paragraph! To speculate, it sounds like there is a text management system being used here that contains each sentence, caption, and heading in the manual in several different languages. You then ask it to spit out the version in language X… but in this case, the tags got messed up and German was mistagged as Swedish or something. Alternatively, it is just a giant word file with review mode turned on, and the translator to Swedish started out with the German version and made changes.  And then someone rejected a pile of changes instead of accepting. The precision of the mess indicates that it is somehow automated.

Quality?

On the second question, I do not think I have any reason to be concerned. Why? Because if the car had been manufactured with the same care as the manual, it would have been obvious. Each door would have been in a separate color, and the features would not match the specification. There would be batteries for a hybrid system installed, along with a diesel engine – in a car sold as a petrol-engined one. Different wheels would have tires of different dimensions, and the headlights would be mismatched… but that is not what we got. The vehicle itself appears to be as solidly made as it is supposed to be.

Looking at this philosophically, I am less concerned since my experience in life has conditioned me to view documentation with skepticism. We have a world today where we really do not expect instruction manuals and documentation to be correct. You always read them with a common-sense filter on, looking for the places where they obviously forgot to test them or missed some update. The impression left by decades of experience as a consumer is that nobody takes documentation really seriously today. Be it for computer software, home electronics, vehicles, or kitchen appliances, it seems that the reasonable expectation is that documentation is always an afterthought that sometimes reflects the real thing, and sometimes not.

It is especially tricky with translations to Swedish. Doing a proper translations does come with some cost – and in particular Asian companies producing cheap stuff seem to just not care and just use google translate with terrible results. I tend to look for the instructions in German or English instead, and sometimes I read all the languages to find an interpretation that makes sense, by vote-of-three redundancy. Chasing a low price and short time to market overrules the need to actually help people use the thing. That might be OK for something cheap and obvious like a USB key or inflatable pool.

However, when you pay thousands of Euros for something, you have an expectation of something better. In the case of our manual, it seems that they have professionally translated from a German original – and then just failed to include the translations into the actual shipping document. The same thing for tools you use professionally – when something is mission-critical, I expect professional and precise instructions. And we have to be willing to pay the cost for that!

In all honesty, I know that writing good documentation is hard, and that testing it and making sure it matches the actual product is hard. Especially for software that changes quickly, going through the docs to find all places impacted by a software change is a tricky problem.

But I digress.

Thinking about Documentation

The key is what we should do about documentation when we produce software and other products, and how we should think about it.

Can good documentation improve the impression of a product? I think it mostly definitely can, especially given the sad state of much documentation on the market today.

Do users pay for instructions?  Sadly it seems to often not be the case, if nothing else because you do not notice the documentation until after you have bought something. However, without docs, much of the capability of a product will remain unknown, inaccessible, useless, and thus valueless. If you bother to include a feature, you have to bother to document it – you cannot expect users to find it by fiddling around. If you want customers to come back for the next version, product, or service you produce, having good documentation for the one they already bought should give a good impression and help retain the customer.

In a world where you have repeat business, documentation matters!

An everyday example of this that most people around the globe knows about is IKEA furniture. While they often sell on price, they do not skimp on manuals. The IKEA instructions are superb and exemplary; they really do work for most people. When I have bought furniture that you have to build yourself from other manufacturers, I am always struck by the poor quality of the instructions. The cheap IKEA furniture looks better by virtue of the instructions.

I am sure IKEA does this in order to reduce returns and the cost of supporting the customers – it not just to give a good impression. But it works. It makes business sense to have good documentation if it can reduce support costs and get customers up to speed faster – and get them to come back.

To me, that is the main thing. Good documentation is worth it, and we have to carve out room in development budgets to actually properly document things.

Docs as Test

Digging into the particulars of computer software and hardware, I think that documentation also serves a second purpose: it helps test the product and prove that we have actually built something usable.

I have experienced this myself, first-hand, many times. Typically, I had been provided with a fresh piece of functionality (in a software product) freshly delivered from of the latest Agile sprint. Given that new functionality, my task was to build a demo or instruction video showcasing it… and it turns out I cannot actually figure out how to work it. Alternatively, the steps as documented in the manual and implemented in the product just seem totally contorted and unnatural when you lay it out end to end. Each piece makes sense, but the documentation is where you are forced to confront the overall flow – and that tends to reveal oversights and gaps.

Another example is hardware design. When the designers of a device is forced to write documentation explaining the programming model and registers and behavior, they often find flaws in the design. As the classic saying goes: only when you have to teach something do you actually understand it. Next, when someone external to the design team reads the documentation, more issues are found. Writing documentation and having someone else read it and use it is a great way to test the usability of a hardware design early on.

Having someone not involved in the development process do the documentation is a great way to test the product and find any issues early!