Re: Documentation Requirements/Standards

[Booth Martin <booth@xxxxxxxxxxxx>]

I ran into this problem at one shop and as we looked at it we realized 
that we had neither the desire nor the budget to document the whole 
system.  Heck, none of us even really knew how it all worked anyway.  
We'd worked with the system just fine since the 1970s.  We did realize 
however that we had annoying problems every time an office employee took 
a vacation or we had unexpected turnover.  Payroll was the really big 
cloud hanging over our head.

What we did was to install a FAQ for the shop, and asked that the users 
& supervisors build it up for us over time.  It surprised us at what 
FAQs got added, and the  splendid attitude of the  users.  When we 
looked at it later we realized that had we taken the energy & time to 
document the system we would have ignored a very big percentage of the 
problems that users in fact were having.  In other words we were glad we 
didn't waste our time providing answers for questions that are never asked.

Here is a link to the Faq Application, with the code.  You will notice 
the dates in the code range from 2003 until a couple of weeks ago.  If I 
were to install it again I would update the code, but the idea is there 
and it can be copied and installed in a couple of hours, if you want to 
try it.

http://www.martinvt.com/Code_Samples/FAQ/faq.html

(as a note, this application was also installed as a VARPG application.  
fwiw, here's the screen shots of the FAQ in Windows and in Java. 
http://www.martinvt.com/Code_Samples/FAQ-VARPG/faq-varpg.html   )



ps: Please notice the subfile scrollbar on the first image.  Its part of 
my campaign for us to use the stuff we have.



Crump, Mike wrote:
> Has anyone taking a step back and determined what their requirements are
> for application/system documentation?
>
>  
>
> Our documentation is all over the map and I want to set a guideline for
> documentation to be used with the end users and support staff.  I have
> some ideas but was hoping for someone to have put this need in writing
> somewhere.  Doing the google search or searching technical writing sites
> has proven fruitless so far.
>
>  
>
> I'm thinking of things like:
>
>  
>
> Brief Description
>
>             Business function
>
>             How launched/where found
>
>             Common name, nicknames
>
>  
>
> How to Identify the Application
>
>             Screen
>
>             URL
>
>             Printout
>
>  
>
> Technical Architecture
>
>             Server
>
>             Application Server
>
>             Interdependencies
>
>  
>
> Workflow Description if applicable
>
>  
>
> Common problems
>
>  
>
> Problem Determination Checklist
>
>  
>
>  
>
> The intent is to come up with something that will assist help desk
> technicians and eventually end users in supporting an application.  So
> much of what we do is based upon OTJ training and assumed osmosis.
>
>  
>
>  
>
>  
>
>  
>
> Michael Crump
>
>  
>
> Manager, Computing Services
>
> Saint-Gobain Containers, Inc.
>
> 1509 S. Macedonia Ave.
>
> Muncie, IN  47302
>
> 765.741.7696
>
> 765.741.7012 f 
>
>
> Make it too tough for the enemy to get in and you can't get out.
>
> This email and its attachments may be confidential and are intended
> solely for the use of the individual to whom it is addressed. Any views
> or opinions expressed are solely those of the author and do not
> necessarily represent those of Saint-Gobain.  If it did, it would be
> folded, mutilated, watered down, politically corrected, and would show
> up a week later if at all.  If you are not the intended recipient of
> this email and its attachments, you must take no action based upon them,
> nor must you copy or show them to anyone.
>
> Please contact the sender if you believe you have received this email in
> error.
>
>  
>
>  
>
>