Authors as User and Technology Experts


October 2000

Authors as User and Technology Experts


On reading your editorial in Best Practices, three thoughts arose in my mind. Two of them related to the experiences of a Tech Writer who described two visits to Defence sites after work had been finished and delivered. (The original account of these visits was published years ago on the Interleaf mailing list.)

On a Navy site he met an absolutely delightful, slim, trim little lady who was introduced as their key maintenance person. She was the only person small enough to fit down the particular access hole and she was also light enough for one of the men to hold her by her ankles, upside down, because there was no room for an appropriate harness! There was also no room for the manuals anywhere in this particular operation, so they just tried to remember what they needed to know.

At the other site he saw one of the maintenance crew working with the delivered aircraft maintenance manuals. The fellow was standing in the middle of the compartment, reaching on tip-toe up into the giblets of whatever he was working on above his head and the manual was carefully folded open on its lovely spiral binding-on the floor between his feet!!

The writer said he learnt a lot about user requirements that day.

The third thought relates back to my own experiences and although it pre-dates you introducing me to the Information Plan, it involves the same principle. Who is the real consumer of what we write? In the Defence software business, it sure ain’t the Defence personnel, even though they accept delivery of the document(s). It is really the young graduate who has been hired by the software company to preform fixed price bug fixes in the delivered code. If the Tech Writer makes sure the graduate can get in and out of the task as quickly as possible (by writing clear documentation and ensuring good code cleanups are delivered, etc.), then everyone in the company gets a pay rise in due course. And, by the way, the Defence people will think the books are great as well. On the other hand, if the graduate consumes the allocated money just finding the problem and understanding it and then has to fix it, the company loses money every time.

I found the Information Plan made it easier for people to understand who is their audience and that made it easier to get the focus fixed from the beginning. Furthermore, the Information Plan requires the person writing the plan to state the source of their information concerning the end-user. So, right from the beginning, it means the project manager should know whether we are dealing with a well-defined or guesstimated user definition and can take action accordingly. In my opinion it is all about establishing the discipline to require processes/tools to be followed/used and then everyone else can make decisions knowing the quality of the information.

I have always maintained there are three kinds of Tech Writers:

  • Production Writers (a courtesy title only) for the person who makes the final set of files into the finished, deliverable product.
  • Technical Editors (the vast majority) who at one end of the scale can work with the near to finished work of the document author or on the other end of the scale, can work with the first draft provided by the author to develop the material accordingly.
  • The Technical Author (few and far between) who can prepare the material from scratch for the document owner to edit/annotate as required and to finally claim as their own work which they submit.

The first category knows nothing about the users. The second category generally assumes the author knows what the user requires and so often pays less attention to the user aspects of the work. The third category, as the author, takes the responsibility of serving the user and if unwilling to take that role, then should not be allowed to start the job in the first place.

At the end of the day, it is the combination of the Project Manager and the role the Tech Writer accepts/adopts that will determine whether the book will suit the user because these two people are responsible for signing off the Information Plan.

No plan means “this documentation is not user considerate.”

Robert Phillips
Lasotell Pty Ltd