re. VB tech doc

["John E. Neil" <johnneil63 -at- hotmail -dot- com>]

I am a student TW in Canada and just completed my co-op term with a Canadian 
bank. Although my knowledge of VB is very limited and SQL even more so, I 
was able to complete 4 of the documents that you described for programs 
containing between 12 and 32 forms, modules, class modules and so forth.

What I did was create a template, which I will try to forward to you (I do 
not have it on this computer). If you view the hidden text (Tools > Options 
> View tab > select Hidden Text) you will see how I completed each section.

Basically, section 1 was a brief overview of what the program does, section 
2 was a data flow diagram created using Visio (now owned by Microsoft).

In section 3 I described all of the pieces that were not a part of the 
program itself (such as logs, reports, ini files, the database(s) etc).

Section 4 was a description of all of the VB modules, forms, etc. For each 
of these I gave a 1 paragraph description (including how this unit related 
to the others in the application), used Snagit to show a screen capture of 
the relevant form, and then created a table for each function and subroutine 
where I listed the routine (in the order that it is written in the code), a 
description of what this part does ("this routine extracts fields.... from 
the database xxx.mdb and ..."
These descriptions also listed fields that were accessed, mainframe stored 
procedures that were used, and so forth. Sections 3 and 4 made up a good 60% 
of the whole document.

Section 5 was a brief user guide (included a Visio chatr showing application 
procedures.) Section 6 described the processes running in the background 
(OCX, for example). Section 7 was ??? (I forget!!) And section 8 was the 
appendices.

It may seem that sections 5 & 6 would be better placed at the start of the 
document but, as this document was designed for the programmers and program 
support personnel, these sections were less relevant for them.

I was the first tech writer that this department had ever had (typical!!) so 
part of my role was to develop this template so that all subsequent 
documents would be consistent - i.e. no matter the application, the support 
personnel knew that section 4 had the application components and section 8.4 
was the installation requirements....

No matter what I have written here, what I think you need to do is find out 
who will be using these documents, ask them what they need, and create a 
template that addresses these needs in a way that they can get to the 
specific section that they need as soon as possible. Then review with the 
users as you develop the material. For example, after the first draft they 
wanted me to have the main (parent) form listed first in section 4, even 
though the rest of the form files came after the module and class module 
files in the document... They do not want to read the whole document, only 
the part that deals with their job at hand. Ease of navigation and locating 
of information is very important.

Comments welcome.

John Neil
Seneca College, Toronto, Canada

_________________________________________________________________________
Get Your Private, Free E-mail from MSN Hotmail at http://www.hotmail.com.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com or 800-463-6627 for more about our solutions.

---
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.