Re: Sentence structure: Indeed it depends

[Tracey May <tracey -at- INTERCON -dot- COM>]

> Another example would be a procedure in which-- as in many I've seen,
> and perhaps in some you've seen-- the user is called upon to perform
> steps the individual purpose of which means very little at the user
> level.

It may mean _very little_ at the user level, but usually it means
_something_. When I encounter documentation that merely
tells me what to do, and not why, I feel as if I'm missing
something. I want the big picture.

Most of the people I know enjoy learning. I don't think it's our role to
simplify everything to the point that our users are unable to grasp
the concepts behind the technology we're walking them through,
that they're not able to see similarities in processes because they
don't understand the processes themselves.

It's a little more work to explain why something should be done,
but I think it's worthwhile. I'm not saying we have to turn user
guides into text books, but I think it's reasonable for us to
explain succinctly why a particular action should be taken.

Putting an explanation after the action works for me.

        Tracey



> You could say,--

> 4. Now you need to decompress your data files.
>    To do so, type dcmprs.

> But why force the reader to deal with that extra explanation of an
> interim step of the procedure, when all that interests the user is
> the ultimate result of getting the software installed?
> You could say just--

> 4. Type dcmprs.

> That is, don't ask questions.  Just do it.  But if you were
> feeling avuncular, you could put the explanation after the action:


I prefer this.
> 4. Type dcmprs.  The dcmprs (decompress) command translates files out
>    of the especially compact form they were delivered in and into a
>    form that can be used.