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.
When we document a procedure we may not use all of the controls presented in
a given dialog box. Use the appropriate warnings and notes that are
applicable to the specific dialog box controls you reference in the
If you've already described the controls on a given dialog box, there's
usually no need to describe them again in the context of a procedure unless
there are specific "gotchas" related to individual controls. However, a
link/cross-reference to the reference material for the dialog box is
Mike Starr WriteStarr Information Services
Technical Writer - Online Help Developer - Website developer
Graphic Designer - Desktop Publisher - MS Office Expert
Phone: (262) 694-1028 - Tollfree: (877) 892-1028 - Fax:(262) 697-6334
Email: mike -at- writestarr -dot- com - Web: http://www.writestarr.com
----- Original Message -----
From: "Claudine CHAUSSON" <claudine -dot- chausson -at- jwaretechnologies -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Thursday, August 13, 2009 9:06 AM
Subject: Writing procedures
> Hi everyone,
> This is my first posting on this list though I've been reading it for
> quite a while now. Beforehand, forgive my English as it's not my native
> Quite recently, I've changed job. In this new software company, there's
> hardly any existing doc so I'm almost writing everything from scratch,
> especially procedures. I haven't done that (writing from scratch) since
> my degree in technical writing and I need some refresh on a few
> fundamental things.
> 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.
> So my questions are:
> o In my procedures, should I repeat warnings and notes? Or is a simple
> link to the interface description enough?
> o Should I list options and describe their possible values all over
> Note that when I say "repeat", or any similar word, I'll be using DITA's
> conref functionality.
> I feel like I shouldn't need to repeat this information again but as a
> lone technical writer, some help will be appreciated.
> Claudine CHAUSSON
> Technical writer
> JWARE Technologies
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-