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.
>There are a few of us now trying to put some method to our madness in an
>effort to get the information we need to do our jobs better. (This includes
>documentation and QA.) We are working with a particular developer who is
>keen on seeing a more methodical and orderly design process put into effect,
>which would include more and better developer documentation. We are
>discussing what developer documentation should look like so that we get the
>information we need without imposing so many new documentation requirements
>on developers that they will balk at writing them.
>Thus, I am wondering what kinds of developer documents tech writers are most
>familiar working with and find the most useful. Thanks for your help.
My book (see links in .sig below) is about how to document the
information needed by UI designers, programmers, testers, and of
course the folks who write the user's manuals and on-line help.
Here's a quickie exposition of internal documentation needed on
Describes the problem domain and the effects to be achieved
there. With the exception of special problem domains like
documents in a word processor, the problem domain is the
world *outside* the software.
Written by the "analyst" or "requirements engineer"
(regardless of job title). Read by the UI designer, testers,
and tech writer; usually of less interest to programmers,
since programmers usually implement interface designs, not
requirements (see below). Also read by the customer to verify
that the software is really addressing what the customer is
The requirements document should not usually be usually long,
complex, or difficult, since it tells you just the information
about the problem domain that you need plus all the
project-specific criteria for evaluating all other design
decisions. You know, that elementary stuff that's so hard to
dig for, is fundamental to understanding anything else on the
project, and can usually be explained very simply and briefly,
like "When they load gravel into a truck at the quarry, they
take a little sample of the gravel and analyze it in a special
machine later on."
Interface design document(s), or "specification":
For a user interface, contains operating procedures,
screens, and everything that every doodad on the screen does
and means to the user.
For an interface between software and hardware or between
software and software, describes the communication protocols
or API, typically in terms of state transitions or function
A UI designer should write the UI design doc; programmers or
analysts should invent communication protocols and APIs and
document them. Programmers read interface design docs to find
out what to implement; testers read them to design test
plans; tech writers read them to find out what the user needs
to do and know.
A log of changes successfully implemented, along with which
release contains the change.
The programmers and testers should generally write the change
log, with the tester having final say about what goes in.
The tech writer reads the change log as a first step toward
writing release notes and updating user's manuals; the
programmers and testers read the change log to see who's been
messing with what and to adjust their own designs.
Procedures for exercising the software to verify that it
really produces the effects intended, either at the interface
or in the problem domain. Normally read and written only by
testers, though programmers and analysts might want to review
them to check for possible holes in the coverage.
I think that in most cases, it's not necessary for programmers to
write program design documentation. Most of that information
should be in the source code. Unless the design has something
particularly tricky in it, a few graphics ought to be enough to
supplement the source-code comments.
On most real-world projects, typically the more important the
information, the less likely it is to be documented. If you're
looking to cut corners, I'd recommend giving priority to the
interface design document. The requirements and problem domain
can often get away with being foggy or embodied only in an oral
tradition, but on a project involving at least two people, the
details of the interface *always* need to be thought through and
made available to different people.
One reason that people avoid writing this kind of documentation
is that many company templates and "industry standards" turn the
internal documentation into an end in itself. There are sections
upon sections of no particular interest to anyone, containing no
information that relates to any particular job. The relatively
small amount of information that you really need is often missing.
I recommend writing these documents in as terse a form as
possible, depending heavily on tables and diagrams, not trying to
write a narrative or Victorian novel. This keeps the documents
short, simple, useful to the development team, and, believe it or
not, not so difficult to write. The hard part should be
inventing the designs, not writing them up. "Just the facts,