TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Jane Bergen is <<...writing a user guide for a 3-year old in-house
program for which NO documentation (except some pretty minimal
online help) has ever existed. No formal training has existed either.
The program is... pretty bizarre, actually.>>
Paging Scott Adams... <g> From your description of the product, it
sounds like this is a wonderful opportunity for you to get involved in
product (re)design. There's an old truism that you can't produce
truly good documentation for an inherently undocumentable
product, and there have been some excellent case studies of how
re-engineering software or hardware to meet user needs can
dramatically improve the company's efficiency, thereby repaying
the additional development efforts and even generating ongoing
savings or profits. That being the case, can you work with them to
(incrementally) improve the usability of the software? For example,
since they've already ported the core algorithms, and are doing
heavy reprogramming already to move it fully from UNIX (thus,
presumably C?) to Visual Basic, that makes it comparitively trivial
to put a new (inter)face on an old set of algorithms, thereby
creating something that is both easier to use and easier to
document.
Let me propose a hypothetical example you can modify based on
your own situation; I'll assume that there's at least one effective 6-
step process that users must follow to create a new lease, input
the information, route it to accounting for approval, file it in the
database, open it for review, and print a report. That being the
case, the programmers can create a single opening screen with no
menus that lists these six steps; each step links to the existing
subroutines (e.g., dialog boxes) in the software, and clicking the
OK button for each dialog box returns users to the opening screen.
You can do exactly the same approach for any other routines (e.g.,
deleting a lease, rather than creating a new one as I've just
described) and subroutines (e.g., if the approval process by
accounting has its own six-step process). The advantage of this
approach for the programmers is twofold: it retains the core
algorithms, which have presumably been debugged and "proven"
over the years, and it leaves access to the underlying software
intact for users who prefer doing things the old way. There are
many other benefits, not the least being that you can make
extensive changes to the underlying code without changing the
interface (thus, without changing the documentation), and that
makes maintenance and updating much, much easier.
<<...the one complaint from the people training new hires is always
that the new people can't figure out where to go next.>>
That supports my suggestion: create an overlay on the old interface
that tells them precisely where to go next, in what order. I suppose
it's possible to retain a "power user" interface for people who prefer
the old way, but I'm not convinced this has any merits.
<<For example, the menus are arranged by department, but that's
really obsolete now as most of the screens are used across
several departments and some of the menus actually open
duplicate windows!>>
Again, this strongly suggests reorganizing the interface around
tasks, not departments. Then you could create separate "show me
all the steps, in order" interfaces for each department after you've
done an audience analysis that lets you figure out how each
department prefers to work.
<<I'm stuck with the unintuitive interface...>>
Sometimes you really are stuck. But in the software projects I've
done to date, I've found that developers are reasonably open to
interface suggestions, particularly when I walk them through a
redesign to show how much simpler it is for the user. In some
cases, I've also demonstrated to them that the resulting code is
easier for them to develop and maintain, and that makes the sales
job a whole lot easier.
<<My thoughts have been to trace the life cycle of a piece of
equipment from purchase to its retirement, and organize the
document accordingly with a separate chapter for the finance-
related tasks that are not necessarily tied to a piece of
equipment.>>
Sounds like an excellent, effective approach to me. Just make sure
you talk to _each_ of the departments to confirm that the life cycle
approach really does match the way _they_ work. It'll probably be
close, but you might find that (say) the sales and finance
departments have different approaches from everyone else and thus
have different needs. You noted that:
<<The users range from the GED graduate hired away from the
WalMart warehouse to marketers to accountants to...>>
And this strongly suggests that your audience analysis should be
based primarily on the tasks the people do, not on their
educational background. If they're brought in to fill a specific role,
then it's a good bet that the company feels they're qualified for that
role, or can be trained to do it. That being the case, you can focus
on the roles and tasks rather than on the user's background.
Secondarily, of course, you'll still have to choose language that
works for a diverse audience (with a broad range of linguistic and
academic backgrounds) within each role, but it's easier than most
people think to write clear, simple text that doesn't talk down to
anyone.
<<Thanks for any advice. And I truly apologize for the length.>>
Simple problems have simple explanations. Complex problems, on
the other hand... Best of luck.
