Writing procedures

["Claudine CHAUSSON" <claudine -dot- chausson -at- jwaretechnologies -dot- com>]

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

Mail/to: claudine -dot- chausson -at- jwaretechnologies -dot- com
http://: www.jwaretechnologies.com


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

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