Info for techies needs detail inappropriate to end users.
There are many tools that can help streamline the process.
Reporting standards ... I have some users who tell me they ran some
program, they got some crazy error message (they SAY that "crazy error
message" not WHAT it was) ... I run the program, can't get it to fail, tell
them that I need a screen print of the error message before I can
proceed. I have given up trying to train people to put cursor on error
message and press the help key.
TIPS ... at one employer I would constantly get complaints about "garbage
on my screen" in which 90% of the time it was a handful of samer messages,
with things like printer needed forms change or was out of paper, or the
item # they had keyed into inquiry was invalid. So I created a booklet
titled "garbage on my screen" with pairs of pages. On left side was
illustration of screen with error message or whatever. On right side was
instructions what to do if this matched your situation. The frequency of
that complaint dropped precipitously.
Company e-mail can be used to send EVERYONE something. This should be used
in EXTREME MODERATION when there is a lull in work volume, to give people
tips on common problem areas. The e-mail support software should have info
on the volume of e-mail flowing through the company, so you know when to
avoid doing such a broadcast.
Programming standards ... every output needs to name iteslf & maybe
library, in a place where easy to extract ... last year I generated a bunch
of ad hoc green bar reports, used Ops Nav to import into Excel which got
sent the auditors. Now they are asking for the same reports
again. Without name of program, the easiest way for me to figure out what
they are talking about is for them to transmit to me a copy of what they
got last year.
For the past 20+ years I have been working with packaged software that
comes with its own standards. In the first 20+ years of my career I worked
with home brew, and developed my own standards, which were expressed as
guidelines or goals, since most software at any new employer lacked any
standards. Basically I applied my standards any time writing a new program
or doing modification on a prior one.
Programming standards serve multiple goals, the main ones for me being
* If an end user has a problem, they identify where the problem is, and the
programmer knows what they talking about in minutes, instead of it taking
days to figure out what they talking about
* When we study some program that has an alleged problem, without
documentation, it can take us days to figure out what it is doing, let
alone diagnose the problem, but with proper documentation it can take us
less than an hour, even with a program that is 100,000 lines of
code. Thus, the first time we go into some program that lacks proper
documentation, adding that is critical, to help us the next time there is a
problem
* Fortunately, it is pretty rare, but sometimes one modification causes
some other problem, so every program has a diary up front where there is a
code associated with what did we do for what reason, then that code is a
comment where the modification happened, so we can then search for all the
places in the code that got changed by some modification. For every 50
modifications I make, maybe 1 needs to be reversed.
In more recent times, I have tried to apply SOA to the evolving standards.
Basically, if we need to have the same subroutine in 20 programs, it is
faster when developing one program to just copy the subroutine, but if we
later need to modify the 20 programs in a series of 20 iterations, it is a
heck of a lot more efficient if the one subroutine is one place.
We can use object list tools to cross-index
sort by description of program, what menus it on, but need to consolidate all
My boss was asking me to rerun a query. He was using a description.
Turns out he was misusing the description, and it was a program, not a query.
Basically MANY users, managers, auditors etc. refer to inquiries and
reports by the description that shows up at the top of page or screen. We
techies need to have a cross index that will tell us what program or
whatever that is in what library.
Many times end users have speculations what went wrong, that upon IT
investigation may determine that their speculation was off base, so there's
the question of HOW DO YOU KNOW the problem is as described?
Then there is the issue of seriousness.
How long can we live with this broke?
Emergency ... our corporate dept budget will pay the overtime to rush fix this
Estimate $ consequences to the company if we continue to exist without this
getting resolved
A FAQ or WIKI is a great idea for co-workers to share tips how to be more
productive, and post general questions, but it does not solve all sins.
In enterprises governed by certain industry regulations, you need to have
some kind of change software management solution to track who approved
software changes, and how the solution was verified to be correct. There
are multiple soultions out there for this, and many of them come with tools
to assist in the overall process.
ISO certification exists for software quality, help desk, computer
security, etc.
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.
--
This is the Non-Technical Discussion about the AS400 / iSeries
(Midrange-NonTech) mailing list
To post a message email: Midrange-NonTech@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/midrange-nontech
or email: Midrange-NonTech-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at http://archive.midrange.com/midrange-nontech.
midrange.com
