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.
Consider writing an "annotated outline" that describes what information
and what format it will appear in. It tells you exactly what to expect
and is easy to review. And once it's approved, the writing is a piece of
cake!
For example,
*Outline:*
3. XMPL System Inputs
3.1 Data Sources
3.2 Data Receiver
3.3 Data Checking
*Annotated Outline:*
3. XMPL System Inputs
This section briefly (1 paragraph) lists and describes the types of
inputs XMPL handles, and introduces the contents of the remainder of the
chapter.
3.1 Data Sources
This section (about 3 pages) lists all the possible data sources
alphabetically and summarizes them in a table with headings: (TBD) For
each data source, it describes where the data comes from, what form it
is originally in, and what you have to do before you can load in into XMPL.
3.2 Data Receiver
This section (about 3 pages) describes:
* What the receiver does, including searching for specified files,
ensuring that files are complete, writing an output file, and
deleting the input files once they are successfully processed.
* How the receiver works including how it uses wildcards, performs
specified volume/library, or total disk searches, how it uses
transaction lookup file (TLF) functions, and explains session
functions.
* What the receiver requires, including the TLF and its purpose and
contents, the data input files and their requirements, and the
control parameters.
* How to tune the receiver to handle specific transaction types
* How sessions are established and controlled, and how they are
affected by the TLF and control parameters
* Information about the session output file that is created
3.2 Data Sources
This section, about 2 pages explains the data checking that XMPL
performs automatically, including listing error messages
(alphabetically) and their meanings; explains the auxiliary checks that
you can perform to obtain more detailed information; and explains the
process you must follow with error-free data. There will be frequent
references to Section 5: XMPL Data Correction.
My 2¢,
John Garison
James Barrow wrote:
Typical use case format. The bosses liked it, but wanted a table in
addition to everything else above. In this table they want columns
showing the Actors, Business Rules and Metadata. I'm guessing that
this Metadata is going to be the encoding a user does to the data
before it's entered into the DB.
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com
