Documenting a product with no specifications?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Edwin Tudsbery  is <<... writing a manual for a product with no specs. The
developers don't write anything about what they're up to, and what they're
planning for the future. Part of the problem seems to lie in the fact that
most of the source code for the product is licensed from another company...
What can I do to persuade the developers to put their ideas
to paper?>>

One useful strategy might be to get the specs for the source code from the
other company; if they've licensed the code to you, they probably also
provided a checklist of what the code does. (If not, your manager might be
able to coax them to provide a copy.) That would let you at least document
the plumbing, which is the most important part; you could go back and work
on documenting the interface later in the development cycle, as it begins to
stabilize.

In the meantime, developing a good working relationship with your developers
is a good first step. This doesn't guarantee that you'll be kept up to date
on the changes (e.g., it has only worked for me about 1 time in 3), but at
least it improves the odds that you'll be kept up to date and that you'll
have a good enough relationship to visit the developers and ask questions.
Regular visits are a good way to keep up to date on what's happening, so
long as the visits don't become annoying. One thing that has worked well for
me is to develop a reputation as an interface expert, which I'm not, but I
have been able to convince them of usability problems, persuade them that
there's a simple fix (even if that fix took me a bit of sweating to figure
out), and demonstrate how stabilizing the interface based on that fix would
make their job easier. Once they understood that doing the interface right
the first time would save them having to redo it a dozen times, they started
taking my advice about how to fix things as I worked on the docs. Since we
reached that point in our relationship, I've been able to make notes while
working on the documentation about areas of the software where the interface
was in flux and work with them to propose stability. I'm also informally
part of the development team, which helps.

But it's an ongoing struggle. Much of the problem here is that software is
about 3rd on our list of priorities (our guys mostly do field research), so
I have to lead them through the same learning curve each time we start a
project. We've
recently hired a full-time programmer, so my mission this summer will be to
work with him to develop a means of stablilizing the interface early on so I
can document while he programs.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer