Writing User Guide for code

[Keith Jeremy Posner <posner -at- SODALIA -dot- IT>]

Hallo all

I am planning a set of documentation for a product which is  code-based
rather than GUI-based. The product works like this: the user wants to
translate input records having one or more structure to output records
having one or more structure. The output record structures are
invariably different to the input record structures.

If you want to read this mail quickly, please go to the last paragraph
now. If you want to know more about this product, please go to the next
paragraph and continue reading.

---> We have written a grammar, a set of syntax structures using which
the user can perform (within reason) any data translation required. For
example, the user might want to perform a lookup operation- the input
data says '9', there is a lookup table of US states: 1=Alaska,
2=Arizona,....., 9=Delaware,... and so on; the lookup operation will
ensure that whenever a record is received in which a particular field
contains '9', an associated output field will return the string
'Delaware'.

To define a lookup operation, the user writes code using the syntax
structures allowed in the grammar. It's a bit like using English or any
other language: I want to ask for an ice cream, how do I structure the
request? (Of course English is a bit more complex - 'Give me an ice
cream!' is syntactically correct but may not always be appropriate.

---> Anyway, to cut a long story short, I'm trying to outline the user
guide for this product. Common sense and experience tells me that I
should list real world tasks, ie things the user actually wants to do
with this product and then the content of each task will give examples
of code (i.e. specific syntax structures)  that will achieve this task.
Can anyone suggest an alternative approach to planning a user guide for
this type of product?

Thanks

Keith
--
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Keith Posner                    posner -at- sodalia -dot- it
Technical Writer

Sodalia SpA
Via Valentina Zambra, 1         Tel: +39-(0)461-316159
38100 Trento                    Fax: +39-(0)461-316217
ITALY
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^