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.
Subject:Writing User Guide for code From:Keith Jeremy Posner <posner -at- SODALIA -dot- IT> Date:Fri, 29 Nov 1996 12:19:20 +0100
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
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?
Keith Posner posner -at- sodalia -dot- it