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