[Framers] What causes documentation to fail

[Nancy Allison]

    Even if SMEs cooperate and tech writers are employed to do the work,
   these things can cause failure:
   1. An inability to understand writing for an end user. I am still
   seeing writers dump every piece of technical information they receive
   into lengthy descriptions, but fail to shape it for the concerns of the
   user.
   2. Omission of background and contextual information that is critical
   to understanding the current topic. Such information may be provided by
   a link to a different topic, but it must be presented somehow.
   3. Omission of this critical information: why the reader should care.
   What is the purpose of using the feature. What problem does it solve.
   What happens if you don't use it. What happens if you don't change the
   default values.
   4. Poor choice of graphics. I've recently been seeing huge screenshots,
   with no highlights, circles, callouts, nothing, plunked into the
   beginning of a procedure, evidently as some kind of establishing shot.
   The sprawling screenshot has no real purpose, but the reader has to
   puzzle over it for a minute before concluding that it is worthless. In
   addition, I've seen UI elements cropped so tightly that there is no
   location information. What's the point of a cutout of a radio button
   and label all by themselves? Give some hint as to where to find them.
   5. Poorly written sentences and weirdly flowing paragraphs. I'm sorry
   to say, there are tech writers with decades of experience who evidently
   have been able to keep employed because they have a technical
   background and talk easily with engineers. Their actual writing is
   awful.
   Hope this isn't too negative. But, let's be honest, an incompetent tech
   writer can produce many types of failure that result in an
   all-but-useless document. I've seen it.
   Happy Friday!
   --Nancy