Communicating with programmers?

[Geoff Hart <Geoff-h -at- MTL -dot- FERIC -dot- CA>]

Archie Ziviello can't <<... develop user guides fast enough...
during implementation we have significant amounts of
interface design change...  The design of the system is
essentially the same except now we have a new screen which
is "doing it all in one shot.">>

That sort of chaotic development process is tremendously
inefficient and likely to lead to disastrous results. It's kinda
like bronco-busting at a rodeo: really good programmers will
come out on top of the horse at the end, but wouldn't it be a
smoother ride if they picked a riding horse to begin with? It's
worth doing some research (I'm sure techwr-l can provide the
appropriate documentation) and presenting your managers
with a proposal for a more rational development process.

<<Therefore I can provide NO USER GUIDE when the
system is turned on because I can not change 156 pages of
reference guide into 25 pages of user guide with a wave of
my hands.>>

You might be able to solve this problem by making as much
of the information as possible available as context-sensitive
online help. If the underlying code is the same, then all the
reference information you wrote remains valid. All you need
to do is rewrite a single "front end" page that links to the
appropriate part of the reference material. You can do this in
print too, but it's more work and trickier to implement. The
hardest part of this is recognizing what's truly going on under
the surface, and documenting that. Then all you need to do is
put the "interface" on that description once the software
interface stabilizes. Trivial example: "This module is all about
printing. You do X [note to self: document this once it's
stable] and you'll get pages out of the printer." Then
document X (e.g., "press control-P", "select Print from the
Random functions menu", etc.) only once things stabilize.

<<I want to get more from the programmers... a system
feature can be off-system in a PC mainframe development
program for days before I see it in the mainframe's test
environment -- time lost.  Second... Since I work exclusively
off the mainframe,  I see F-keys pop up like worms after a
spring rain.  I can explain a complex, in field method to
support a feature one day and the next WHAM! we've an F-
key for it and the method has changed.>>

The problem seems to be that there is no clear design goal,
and that the programmers are working on their own rather
than aiming for any formal, more-or-less final design spec.
That being the case, you're facing a mighty nasty political
problem: you have to point out to someone that the
programming manager (PM) isn't really managing anything.
You obviously can't tell the PM this without making an
enemy, so you have to go one step higher up the food chain,
and that can lead to even more bad blood. But if you can
reach the next level of manager and make your case
persuasively (with the demand for change passed downwards
without identifying the source of the suggestion), this may
work. That kind of power play is tough, so there are subtler
tricks to try first (see below).

<<How do you manage your effort when there is no clear
expectation of you other than "to write the manual.">>

I tell them I'll start writing only once the interface is stable,
but I really don't recommend this as a survival strategy unless
you've built some serious credibility with your managers. (It
can also backfire. Now, for instance, I've taught them this so
well that they're reluctant to give me the current version of the
software until they're satisfied that it'll be relatively stable.) In
your case, the trick would seem to be to document the
underlying functionality early on, since this won't change
much, then tie it all together with an overview page or pages
that you write only once the interface shows signs of being
stable. Trivialized example: "This module lets you calculate
your salary after taxes. You'll need the following inputs: gross
salary, city, state or province, country, number of dependants.
Here are the details of each..." (That's the part that doesn't
change.) "Input your data in the following, seemingly random
order:..." (That's the part that does change.)

<<I spend hours trying to write out procedures with little to
no explaination of the screen.  I spend enormous amounts of
time trying to shoot holes in tasks.>>

You're doing two things here: First, you're testing for bugs. If
that's just a value-added service and not formally your job,
stop doing it now and leave the work to "quality assurance"
(assuming you have such a department, which I'd speculate
you don't). Debugging unstable code is wasting time you
need to be spending on documentation. If you must debug,
wait until things are stable or (much better) debug the
algorithms they're using (e.g., "Say, dude, don't we have
states in the U.S.? You've written "province" here in your
algorithm."); that way, the bugs you're finding never make it
into the code you're documenting. It occurs to me to wonder
whether your programmers are actually writing out this
pseudo-code, or just programming blind; when I learned to
program, I was taught to write out "pseudo-code" first to
describe the algorithm (e.g., "get the person's name, perform
the following validity checks, then store it in the database if it
passes the tests; if not, explain the problem and get them to re-
enter the data), then translate this into the actual programming
code. Maybe you could help them edit their pseudo-code?

Second, while all the random interface changes are going on,
you're learning the software... not the interface (which isn't
stable), but rather what it does and how it does it. If you know
that the interface is going to change, don't try documenting it
just yet: get a feel for the interface and what the software does
instead. When you come back to the near-final version and
the interface has more or less stabilized, the actual task of
documenting the code will go much faster.

<<What suggestions can I make to the management to give
me something constructive to pursue?>>

Working with management may be counterproductive given
that you'll have to point out to them that they're not doing
their jobs. Even if they are trying to do their jobs, and failing,
you're facing a major change in the way the company
operates. I doubt you've got the influence (as a techwhirler) to
push the change through, and even if you did, it'll take some
time for people to adopt the change in their daily work. It
might be far more productive to start working very closely
with the programmers. (I've stated this so many times that
people's eyes start to glaze when I say it again, but if you
don't have a good working relationship with them, you've lost
the fight before you even begin.) Explain your problem and
see if you can get them to come up with a way to make your
life easier (e.g., warning you that an interface is temporary vs.
confirming that it's "nearly done", or perhaps working with
you to develop interface standards right from the start). Once
you've gained their respect and maybe even friendship, they'll
be willing to make efforts to make things easier for you; until
then, you won't see any changes.

<<would a GOOD manager realize this or do I have to have a
presentation on why week to week I'm being hamstrung in
my effort?>>

There's no question you have to communicate the problem to
_your_ manager. There's a distant chance that your manager
can resolve the problem by bumping it higher up the food
chain, but even if that doesn't happen, at least your manager
will understand what you're facing and have a little more
sympathy for you when it comes time to appraise your work.
But in the best possible case, your manager may have the
clout necessary to talk to the PM and get some changes made.

--Geoff Hart @8^{)}     Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Perhaps there is something deep and profound behind all those sevens,
something just calling out for us to discover it. But I
suspect that it is only a pernicious, Pythagorean coincidence." George
Miller, "The Magical Number Seven" (1956)

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=