TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
...The root of the problem seems to be the writing style I've
> chosen for our documentation. I made a decision (based
> on what I saw other software companies doing with their
> documents) to write instuctions in full sentences using
> bold type to identify buttons, menus, menu commands, and
> other inputs. An example of this would be "From the
> <b>Edit</b> menu, select <b>Merge</b>." I usually tie
> these step-by-step instructions to a task that the user
> needs to complete.
>
I use the same style. An example might be as follows:
1) Press Alt+ Enter to maximize the "Welcome to PTC Version 2.6 screen",
(Figure 17).
2) You will be asked to confirm the date and time. If correct, press Enter
for the date and Enter for the time.
The Main Menu screen in Figure 18 will be displayed.
3) Highlight Control Menu (second line) and press Enter.
The Control Menu screen in Figure 19 will be displayed.
4) Highlight Clear Batch (sixth line) and press Enter. When asked to
confirm, select Yes.
You will still be at the Control Menu. Highlight Transaction File
Control (third line) and press Enter.
However, my instructions when creating documentation is to write the
instructions so anyone, with no prior experience, can pick up the document
and run the process.
> My instinct and professional trainging says I shouldn't just
> blindly follow our developers when they request a change in
> the style or presentation of our documents, especially if their
> only reason for requesting a change is "That's the way I like
> to see it done" ?
>
>
You might you consider a bi-level document. I've used the conditional
feature of Frame to filer out the material that an advanced user might not
need, such as a screenshot of every dialog box (beginners like it for
constant confirmation and verification), and the subordinate instructions
(such as the lines between each lettered step in the above example.)
> Do you think I should drop the full sentence instructions and
> try something like "Edit --> Merge" ? This would satisfy our
> developer's desire for brevity, but it isn't exactly elegant.
>
Elegant-shmelegant...You are in compromise mode. Either you make an effort
to accomodate them without losing site of the basics, or they will loose
site of you.
> John Posada, Technical Writer (and proud of the title)
> The world's premier Internet fax service company: The FaxSav Global
> Network
> -work http://www.faxsav.com -personal http://www.tdandw.com
> -work mailto:posada -at- faxsav -dot- com -personal mailto:john -at- tdandw -dot- com
> -work phone: 732-906-2000 X2296 -home phone: 732-291-7811
> My opinions are mine, and neither you nor my company can take credit for
> them.
>
> "One ought, every day at least, to hear a little song, read a good poem,
> see a fine picture, and, if it were possible, to speak a few reasonable
> words.", Goethe
> "Say all you have to say in the fewest possible words, or your reader
> will be sure to skip them; and in the plainest possible words or he will
> certainly misunderstand them.", John Ruskin
>
