Re: Documentation Requirements/Standards

Another thought, Mike:

How do the projects come into being in the first place? Do written requests come in to the IT Department? If so, is that request the best starting point for documentation? Explaining how the application is used to meet the request itself might keep both the implementor and the requestor from killing each other?

Crump, Mike wrote:

This has generated from our help desk who usually gets stuck with
absolutely no documentation and the implementer having the belief that
they should figure everything out. I want to suggest general
'guidelines' because I don't want people doing nothing but
documentation. A minimum of sorts with some suggestions. Not all things
work the same and I know that a checklist might work real well with
application A and common problems might work well with application B.
I'm also thinking that if no documentation exists then the Help Desk
will just pass the call on to the implementor, which will aggravate
them, and the first demand they will come up with is you didn't tell us
what and how to document.....which will be true but it's a great blame
displacement tactic.
So, I want to emphasize that applications should be documented, here is
what we are looking for (in general), and that if there is no supporting
documentation then the calls will be forwarded on to the developer or
implementor.

I was hoping to find some already 'documented' documentation guidelines
so I didn't have to create a document from scratch. From there then I
would consider tools and methodologies - Wiki, FAQ, Browser, scripting,
etc.
Michael Crump
Manager, Computing Services
Saint-Gobain Containers, Inc.
1509 S. Macedonia Ave.
Muncie, IN 47302
765.741.7696
765.741.7012 f
Those who beat their swords into plowshares will plow for those who
don't.
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.
-----Original Message-----
From: midrange-nontech-bounces@xxxxxxxxxxxx
[mailto:midrange-nontech-bounces@xxxxxxxxxxxx] On Behalf Of Buck
Sent: Monday, January 28, 2008 3:44 PM
To: midrange-nontech@xxxxxxxxxxxx
Subject: Re: Documentation Requirements/Standards

Mike wrote:

Has anyone taking a step back and determined what their requirements

are

for application/system documentation?

We tried the 'one size fits all' at my last place and it was not good. We ended up with a very large document that was very difficult to navigate and understand. Web applications had empty 'Report headings' sections, and reports had empty 'URL' and 'Menu path' sections, etc.

I lobbied to try an expert system (flowchart/guided checklist) but left before any movement was made in that direction. The help desk at my current place is like yours. Informal notes, OJT and osmosis.
--buck