re. VB tech doc

Subject: re. VB tech doc
From: "John E. Neil" <johnneil63 -at- hotmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 08 May 2001 12:54:38 -0400

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.


Previous by Author: RE: So you call yourself an architect? - OT
Next by Author: RE: Is IT growth slowing?
Previous by Thread: RE: So you call yourself an architect? -- longish
Next by Thread: In response to...


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


Sponsored Ads