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.
I write several types of documentation for the bank I work for, including system manuals. Because
the information in the manuals should be useful to different audiences, we structure system manuals
so that some aspects of a system are treated more than once, but from different angles. The basic
outline for our system manuals is as follows (including a brief description of what goes in each
chapter). You may be able to adapt some of these ideas to provide both a task-oriented and a
definition-based approach to the data in different chapters of the manual. I think both are
appropriate.
Introduction: A brief statement of the nature and purpose of the system, an explanation of how the
manual is organized, an explanation of any typographical or other conventions used in the manual.
System Overview: A high-level walk-through of how the system functions.
Files and Record Layouts: A listing, and sometimes description and layout, of the files involved in
what the system does. This may include both external and internal files, and files from other
internal systems.
Adding Records: The types of records that reside on the system, and the ways in which each can be
added. This may include manual input, input from other systems, and external input.
System Processing: This usually describes a processing cycle, and describes how programs process
data, use internal and external input, create and post transactions, etc. Anything that is done by
the system once a program or job is submitted is included in this chapter.
Maintenance and Manual Processing: This is the place to describe the manual procedures that relate
to the system. In our case, this chapter does not include policy or department procedure, it simply
describes the kinds of manual processing allowed or required, and how the system allows or requires
you to accomplish it. The chapter may talk about sequences or formats that must be followed, the
varying effects that can be achieved by choosing one or another option, etc.
Interfaces: This chapter describes how one internal or external source passes data to another, and
any reformatting or other intermediate processing required.
Outputs: We use this chapter to describe any outputs other than reports, such as files, forms, or
notices.
Reports: Although reports are outputs, we treat them in a separate chapter.
Screens and Descriptions: This is where we place screen samples and field descriptions. We do not
include any procedures or other task-oriented material here. We do define the screen, its uses, and
briefly state what processing or other aspects of the system are affected by activity on that
screen.
User-Defined Parameters: Almost every system or application has user-defined parameters. We describe
the method of defining these parameters, and describe their effects on processing.
Custom Modifications: A lot of our software is bought from vendors rather than written in-house.
However, we typically make extensive modifications to the software. We use this chapter to describe
those modifications.
Historical Items: This optional chapter may include items such as parameters or processing that were
in place for a period of time, or anything else of a historical nature. This can be particularly
important in our environment, as we deal with customers' accounts and may have to support research
concerning how an account was processed some years ago.
Appendices: As needed to complete the documentation of the system. These can include tables of
values, transaction codes, messages, etc. We find that there is some valuable material that would
interrupt the narrative flow of the manual, but which should be included in the manual.
Glossary: If needed to explain terms used in the manual.
Best of luck,
Jo
--
Jo Baer
Senior Technical Writer
TCF National Bank
Minneapolis, Minnesota
jbaer -at- -dot- tcfbank -dot- com
The mome rath isn't born that could outgrabe me.
Nicol Williamson
Radwa Darwish wrote:
> Dear all,
>
> I am on my first documentation project, and I have no solid technical
> writing background. In my process of documenting a General Ledger software,
> I had in mind the following:
> - Start with general features.
> - Go through the definitions and tasks windows by giving a simple background
> and then a "How to..?" approach to explain the usage of each field.
> - Add a reference part to list all icons, buttons, glossary, error and
> warning messages and so forth.
>
> The thing is that my boss, who is the software development manager, doesn't
> like the "How to...?" approach and wants me to replace it with a listing of
> each field, edit box or grid and a brief on its usage. I am not quite sure
> that this way will be effective enough and I need your help....Any
> suggestions any innovative techniques or any standardized documentation
> process to adhere to.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002. www.ehelp.com/techwr
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
