Re: Writing procedures

["Mike Starr" <mike -at- writestarr -dot- com>]

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

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 
useful/appropriate.
--
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
> language.
>
> 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
> again?
>
> 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.
>
> Thanks.
>
>
> Claudine CHAUSSON
> Technical writer
> JWARE Technologies 

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

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