Is it unreasonable to write user documentation in the style of a technical book?

Question

Tell me if this sounds familiar:

something something something... as seen in figure 1-1 on the next page...

It's in practically every book I've ever read about programming. So when I was writing a small instructional booklet on how to use some in-house software, which had images of the screen that the user will be on at this certain step I wrote something like "The screen that pops up looks like the one shown in figure 1-1 below."

But I'm thinking: I'm used to that style of writing, but if my target audience is the 'average person' are they going to be confused?

So, more generally, are there any common practices in technical books that should be avoided when writing documentation for average people?

Answer 1

If you want a better answer to your question and a real awakening as to how well you write instructional manuals, hand the lady at the desk your instructions and watch over her shoulder as she tries to follow. Don't interject; pretend your not there. Ask her to think outloud. Take lots of notes. Prepared to be shocked.

Go back and rewrite the instructions with all the feedback you received.

At least with the romance novels, you know who's banging who. Our instructions are rarely that clear.

Answer 2

There are a lot of books describing styles and giving advices on technical writing, but when publishing a book, I think it is a publisher's decision, as to how many pictures it will have (images affect publishing costs), and that can also somewhat influence your style of writing (whether you will reference Figure 1-1 several times, or whether it will always appear below the text, as in a tutorial).

For example, books dealing with courses of CAD tools often choose, for clarity and ease of use the second approach (because user doesn't want to flip pages all the time, but to follow the process of generating a design, for example).

Programming books, from what I've seen more often follow the first example. Since images usually serve only as an aid to the text, the user will get most of its information from the text itself. Therefore, referencing a figure several times is acceptable.

Hope this makes some sense ...