“We can design away the need for a user manual and online Help”
The idea of a product that totally is intuitive to use, the product that sells itself, sounds terribly attractive. Often these are called commodities, and consumers tend to go for the cheapest one, or the one with the best brand image.
There are situations where good intuitive design can sell successfully, and the Apple iPad is probably the most well known example. However, even iPad users seek Help and want user guides.
iPad books at Heathrow Airport
Of course, designing a product that needs less documentation makes sense, as does delivering the content in the right way. If the User Assistance is more effective embedded into a screen than in a user manual, then your Technical Authors should “publish” the information there.
“If you’re working on an Agile project, you’ll avoid wasted time and effort by leaving the documentation to the end”
Unfortunately, if this leads to other wastes, such as the waste of overburden (leading to poor quality or delays), it may cost you more. If it leads to an uneven workflow for the Technical Authors, with gaps in their workload, then again leaving documentation to the end may be a more costly approach.
“Nobody reads the manuals”
Maybe they’re right. Why not test this assumption – use Web analytics to see how many people do read the Help or search for Help.
“If we put out manuals on the Web, our competitors will have an advantage over us”
If a competitor want to analyse your product, they’re more likely to buy one and look at it in detail. There would easier ways for a competitor to reverse engineer a product than by reading your marketing literature or user documentation.
If you don’t have your user documentation on the web, what will happen to all your customers and prospects who search for that information? Hewlett Packard states that 90% of its customers never physically see the product before they buy it. They decide based on product images, text, reviews and H-P’s reputation.
Why not test this concern – start out with one product and measure the results.
“If we put our manuals on the web, we’ll lose Support revenues”
There’s an implication that the products are designed in a way that they will require the user to call the Support line. William Deming proved that it’s cheaper in the long run to have high quality products that don’t go wrong. His approach was taken up by the Japanese car manufacturers, and underpins their approach today.
Why not test this concern – start out with one product and measure the results.
“Research shows you must use the 7+-2 rule for lists and arranging your information (i.e. if you have more than nine items, split it into two lists)”
While it’s generally good advice, there isn’t really any science behind this. It wouldn’t make sense to have the months of the year split into two lists, so use this rule with care.
“Technical Authors want to write too much”
It’s our experience that Technical Authors hate writing content that’s wordy and verbose, or writing content that’s not used.
Having said that, they do like things to be complete. Sometimes, particularly with products that are only used by early adopters, you don’t need to provide a complete documentation set. You can fill in the gaps when other user groups start to use the product.
“Print layouts don’t work on screen”
This used to be true. However this may be changing . Print layouts can work on tablets, with their more life-like retina screens and touch interactions.
“Everyone will need to move over to the DITA XML standard”
Moving to DITA makes sense if you are translating your content, content is being exchanged with other partners, or you have processes that can form sub-processes elsewhere. However, the quality of the deliverables from DITA can be poorer than what you’d get from non-DITA authoring tools. We have clients who have chosen not to adopt DITA, because they can get 80% of the benefits of DITA for 20% of the cost.
Do you agree? Have we missed any out?
See also:
It’s a great point about DITA. I have the impression that it’s used more and more, by management but also writers, as a buzzword rather than understood as a technology to be employed. As such, it is used in error when a more mature tool could/should have been used.
I like all of these; I especially like the one about agile. The best approach is to bring the technical writers in early — to write the user stories. Then the user stories become the basis for the customer documentation. True, there’s going to be some rewriting as the project moves forward. But it’s not like we never had to rewrite when we used the waterfall method.
Agree with on the statement that ” technical writers hate to write verbose content”. I hate it when some developers wants to add any nice to know information in the manual that is not relevant to the user.
Agree with on the statement that ” technical writers hate to write verbose content”. I hate it when some developers want to add any nice to know information in the manual that is not relevant to the user.
“If we put out manuals on the Web, our competitors will have an advantage over us”.
If someone is able to reverse engineer your product through the information in your technical manual, you’re probably doing too well to notice it. I’ve never heard it done; has anyone?
I worked at Cisco Systems for ten years and I often heard different business units expressing the same fear. Cisco management didn’t buy into it and Cisco thrived in an environment where any piece of information that might help a customer went into the manuals.
DITA can be another example of that industry-favourite trope, concentrating on the tools not the outcome. For something that’s supposed to support re-use, and hence you’d think might save a little bit of time, it can add an awful lot of process at the expense of giving the user what they want. Count me as a sceptic.
‘It’s our experience that Technical Authors hate writing content that’s wordy and verbose’. Well, there’s authors and there’s authors – I recently edited some technical guides and cut them by about 20%. That’s quite a lot of fluff.
[…] a post that many technical writers have longed to write, and now Ellis Pratt has. Nine myths of technical writing, which Pratt blogged on his Cherryleaf site, lists nine of the more popular myths tech […]