7

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?

Improve this question
3
  • 1
    "Something, something, something, dark side. Something, something, something, complete".
    – Wizard79
    Commented Oct 21, 2010 at 8:55
  • Who are your users? "Average person" covers a lot of ground, and fails to explain the users' relations to the program. Will the users be constantly using the software, or occasionally, for example?
    – David Thornley
    Commented Oct 21, 2010 at 15:18
  • 1
    @David Thornley: Ideally they are office administration staff, but historically it looks like my company is poaching from McDonalds.
    – Steven Evers
    Commented Oct 21, 2010 at 15:42

2 Answers 2

Reset to default
7

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.

Improve this answer
3

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 ...

Improve this answer
2
  • +1: Indeed it does makes sense. In my case, it's an internal document which isn't likely to ever be printed, so there are no real concrete costs to producing it. I'm more focused on "Will the lady at the front desk, who reads romance novels all weekend be able to follow along?"
    – Steven Evers
    Commented Oct 20, 2010 at 22:08
  • @SnOrfus - Thanks. For the lady at the front desk, however, I'd probably go with the first approach. It is my experience, (from those few tutorials that I've written about, just as luck would have it, CAD tools) newbie users like to follow a "visual process". It is easier for them I guess, since no information "gets lost" while flipping pages (while looking for page 128, he already "forgets" something from the previous picture). Expecially, if the document is not printed, (and bytes don't cost that much anymore).
    – Rook
    Commented Oct 20, 2010 at 23:24

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.