Re: System Documentation

Subject: Re: System Documentation
From: "Wing, Michael J" <mjwing -at- INGR -dot- COM>
Date: Thu, 24 Sep 1998 09:32:22 -0500

I'm not sure if you are documenting a program to explain its flow and logic
or explaining the automation layer of your product and how to exercise it in
VB. If you are documenting the automation layer, my remaining comments
apply. If not, sorry in advance for going off track.

> Should the writer assume that all users of the document are expert VB
> programmers who are familiar with every slick coding routine that your
> programmer could possibly have included in the application? (In
> otherwords,
> how do you decide which sections of code really cry out for explanation?)
I assume that they are fluent with VB (or Delphi, PowerBuilder, etc..). My
automation documentation is to explain the automation of my product, not to
teach VB.

> How much info should accompany an API call?
I document every object, method, property, event, and constant exposed to
the programmer by my product. Each object topic links to it's methods,
properties, and events. Each property or method argument that references
constants links to the applicable constant topics.

Each topic focuses only on that piece of automation (that is, the OpenFile
method explains the syntax, arguments, and implementation of that method).
If a method, property, or event topic has multiple implementations (applies
to more than one object), I explain any differences. If the automation
element affects other elements, I explain in the Remarks section of the

In an object topic, I explain creating and implementing the object. I also
categorize its properties, methods, and events into functional groups. For
example, I may explain that the Document object has methods for file
manipulation (opening, closing, saving, and so forth), imbedding graphics,
and so forth. I explain that it has properties for configuring the
appearance (background color, offsets, and so forth), ...

I do not document workflow in the on-line help. Instead it is reference
help. The philosophy is that the user is in the midst of writing code and
is not sure if there is a method to perform a certain action or is not sure
of the syntax and whether arguments are optional. Therefore, they press F1
(in VB) and get help on that automation element.

Workflow information appears in a companion document. I do this document in
HTML with links to the automation WinHelp topics. The workflow document
also contains complete examples of code (complete being a full application
command or function written in VB for the product). I have also embedded
VBScript code and form controls in the HTML document. This allows the user
top execute the code from the help document. For example, the user can set
document parameters, and then they can automatically open the document with
it set to the customizable settings.

> Is a hard copy manual even advisable -- should the documentation be
> on-line with links to the VB Help?
My documentation is all on-line.

> Does anyone know of a software tool / add-in that extracts the procedures
> /
> arguments from the Visual Basic code (thus punching out a skeleton for the
> systems document)?
Actually, you probably want to extract the information from an object
browser. Some browsers (like VB Companion divide the elements into method,
property, event, constants, object categories). The browser also tells you
the arguments for methods and events. Good browsers tell you whether the
arguments are input or output, required or optional, and the data type.

The OLE2View browser also displays F1 helpcontext numerics (in HEX). I've
won a few free tonics (sorry, I'm done south now, it's Cokes) from
Developers who claim that they put in the help context ids.

I have written a Word macro that takes the print file from OLE2View and
makes a primitive automation help file (even does
object-property/method/event-object linking).

> Many Thanks for your comments and opinions.
> Bruce McCowan, P.Eng.
Mike Wing

Michael Wing (mailto:mjwing -at- ingr -dot- com)
Staff Writer
Intergraph Corporation; Huntsville, Alabama


From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: Linking online doc to an intranet
Next by Author: Re: Has the Web advanced the written word?
Previous by Thread: Re: System Documentation
Next by Thread: Humor in Technical Documents

What this post helpful? Share it with friends and colleagues:

Sponsored Ads