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.
>Application development is looking for a sample that has detailed
>requirements, something a programmer can actually program from. This is
>also to be used as an example for the functional people to show where
>they presently are......and where they should really be.
>
>Presently, application development is receiving high-end functional
>requirements vs the needed technical requirements. "This is what I need
>to gather for them."
What programmers need to program from is a detailed--and I mean
detailed--description of the rules of behavior of the input/output devices
of the machine to be programmed. I call this an "interface design
document". I agree that a requirements document is not enough to code
from, especially if it's "high-end".
I think the best person to prepare an interface design document is the
interface designer. While it can help to have a professional tech writer
help out, what makes the document useful is its contents, and its contents
are purely made-up stuff. So it's easiest if the person who made it up is
also the one to write it up.
The problem with these documents is generally not formatting or
organization. It's usually that the document either doesn't exist, or the
person who made up the interface design didn't think the details through
far enough. That is, what's wrong is usually more an inventing-the-design
problem than a writing problem. ISO and MIL standards generally don't help
with this, by the way. You make a good design by making a good design, not
by following documentation standards.
My book (links in .sig below) includes excerpts from a user-interface
design document from a small, real project. The programmer loved it (also
the tester and documenter). It was open, on her desk next to her computer,
and filled with implementation notes every time I walked by her office.
Also, everyone involved read the whole thing and had lots of
content-related (as opposed to format-related) suggestions for it at the
design review.
It's not perfect, though. The original document was 80 pages. For reasons
of space, I excerpted only about 20 pages. And they set it in Adobe
Garamond, which I do *not* recommend for internal documentation! But it's
still useful, in that it shows you what's involved in documenting every
field, every button, every error message, every menu item, and so on.
However, I think the more useful stuff is the sections that explain what a
requirements document needs to contain and what an interface design
document needs to contain.
