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.
>I have searched the archives but am finding only general discussion and
>theory while I need rather specific assistance.
>I have been asked to help develop a form or template that developers can use
>to document their project processes and content. The actual request read as
>follows: "I am looking for a generalized standard format. It should provide
>a documentation trail for the programmers and a sign-off/buy-into signature
>section as well."
>
>Following is an outline of what we've come up with so far. Suggestions,
>comments, etc. are more than welcome TIA
>
>Scope
>Requirements
> Components Affected
> Description of work to be done
> Computer language to be used
>Considerations
> SQL Statements
> Fields and keys required to obtain data
> Database modifications
>Testing
> Unit testing (developers)
> Input files
> Expected output
> End to end testing
> Input files
> Expected output
>Time estimates by each involved group
>Sign-offs
I'm not sure who is going to be reading this document or what
jobs they'll perform with it, so I can only guess at what would
be useful. But maybe the following will help get you started.
--
I've written a whole book on what belongs in a requirements
document and how it should look. (See links in .sig below.)
Here are some common mistakes to watch out for:
1 Creating a standard table of contents and forcing it onto
every project. Different kinds of project need different
kinds of information.
2 Treating the requirements as a high-level description of the
program, rather than a description of the problem domain and
what the users want to achieve there. I mention this because
you list components, work to be done, and computer language
under requirements, all of which sound like implementation
decisions. Of course, those decisions do need to be made at
some point in the process, and sometimes there is even good
reason to include them in the requirements. The main thing
is not to let this kind of information squeeze out what the
users are really interested in. That seems to be omitted
from your first cut.
3 Omitting user-interface design. The unfortunate idea of
dividing between "requirements" and "design" has led to a lot
of unusable software, because the UI is given to the
programmers to design as a afterthought to programming.
Better is a three-way distinction: what the users want to
accomplish in their world (the requirements), the interface
behavior that will accomplish that (interface designs), and
the internal gizmos and settings of the computer that
implement the interfaces (program design).
I think of SQL statements, tables, fields, keys, and the like as
part of program design broadly defined, even though technically
they're database design. The main thing is that everything in
the interface design should implement something specific in the
requirements, and everything in the database and program code
should implement something specific in the interface design.
When the program design drives everything else, you usually end
up with a mess, more of a artistic statement by the programmers
than something useful to the customer.
--
And then again, maybe you only mean to make a document that
describes how the programmers plan to address changes to
requirements or a UI design, for purposes of scheduling and
estimation. In that case, mainly you need to consult your
programmers and testers, since the specific information varies a
lot from shop to shop (and to some extent, from project to
project).
I can give you some details about what information to include,
but beware that software engineering is not a matter of filling
in the blank in some generalized form. You have to try ideas
out, prototype, abandon ideas, profile the code, debug, etc.
This is moving more into software engineering than technical
writing, so I'll stop here, with just one last thought: having a
standard documentation template is not going to make software
engineering easy or predictable.
For more info, post to comp.software-eng. Be sure to mention
who is going to read this document and what job you expect them
to do with the information--or ask what jobs people perform in
software development and what information each job needs.
