Writing procedures?

Subject: Writing procedures?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>, Claudine CHAUSSON <claudine -dot- chausson -at- jwaretechnologies -dot- com>
Date: Thu, 13 Aug 2009 11:45:31 -0400

Claudine CHAUSSON wrote: <<Beforehand, forgive my English as it's not
my native language.>>

Pas de problème... assez claire, et beaucoup mieux que mon français.

<<I'm developing topics with DITA in order to single-source to help
(haven't chosen a format yet) and pdf. I've described the interface
and now I'm writing procedures for the tasks that can be done through
the interface. I've been quite thorough in the interface description:
all fields, options, and possible values (when a choice needs to be
done) have been described. Warnings and notes have been written too to
call out the user attention to some specific aspects... In my
procedures, should I repeat warnings and notes? Or is a simple link to
the interface description enough?>>

Warnings and notes should be repeated every time they are required.
Never make the reader look somewhere else to find this information,
since many readers will not make this effort. This is the best way (in
documentation) to ensure that readers have a chance to avoid injury,
damage to equipment, or loss of data. Of course, the best way overall
is to design the product to prevent such problems, but that's rarely
possible.

<<Should I list options and describe their possible values all over
again?>>

Whenever the options are relevant, they should be repeated so that
readers are not forced to search for them. (Since you are single-
sourcing, you can write this information only once and insert it by
reference everywhere that you need to reuse it.) Here, "relevant"
means that you believe it is likely the reader will need to learn this
information; instead of forcing them to open a new window or leave
their current thought process (which focuses on the procedure, not
navigating through your documentation), present the information all in
one place.

If you feel that few readers will be interested in details of the
options, it's appropriate to focus on the parts of the procedure they
will pay attention to, and provide a cross-reference to a topic that
provides details of the options for readers who want to learn more.

------------------------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
------------------------------------------------------------------------
Effective Onscreen Editing:
http://www.geoff-hart.com/books/eoe/onscreen-book.htm
------------------------------------------------------------------------

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.
http://www.doctohelp.com/SuperPages/Webcasts/

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
Writing procedures: From: Claudine CHAUSSON

Previous by Author: Finding freelance work
Next by Author: Publishing/editing (for POD) advice sought?
Previous by Thread: Re: Writing procedures
Next by Thread: Re: Writing procedures?


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads