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.
My experience at this company and previous companies is that the
in-house doc set varies by name and scope.
As companies develop, they usually see a need (and eventually start
using them...) for product-related documents first. So there's got to be
at least one document that makes a business case and outlines some broad
functional requirements. If there is one big driving customer for a
project, then the Product Requirements Doc (or spec, or statement,
or...) or Marketing Requirements Doc can be quite detailed, since the
customer meets with your company and they hammer out what they want/need
to see in the product. Your company might additionally decide whether to
build in certain functionality that makes the product a better
generally-sellable platform (beyond that one big customer), makes it
easier to develop/revise/upgrade, makes it fit better with your other
product lines, or allows it to re-use hardware or software from other
products, and so on. Thus, the initial requirements doc covers what the
customer (or the Marketer trying to stand in a customer's shoes) needs
as well as what your company needs in the product.
There's also the matter of timelines. Usually, once Marketing (and Big
Customer, if it was that kind of requirement) have finished beating the
requirements into submission, they want a product yesterday for delivery
targets later this week, already promised... oh, wait, that's the Sales
guys who do that... well, the Marketing people too...
This document might go through several iterations and be tied to
contracts. It should be a controlled document.
Then, there's an engineering response. We used to do HRDs and SRDs
(Hardware Requirements Documents and Software Requirements Docs), but
now we call it a SOW (Statement of Work) with sections for hardware and
software. Engineering says what they are going to do, to meet the
requirements, how close they think they can come (and whether some
aspects/features/requirements might be pushed out to a later release.
Negotiations ensue, mostly centering around resource (people)
availability and conflicts with other projects. When hardware is
involved, there's also the matter of lead times for essential
components.
Usually, each department has a section in the SOW that they fill out,
stating what they believe they're expected to do, and what they intend
to do and on what schedule (roughly).
Depending on the complexity, the SOW might generate a bunch of
sub-documents wherein each department or group sets out what they expect
to do, the risks, the timelines (not necessarily hard dates - more
likely X weeks for this part, Y weeks for that part, Z weeks for the
rest...).
There might or might not be further Product related documents, but those
are the basics - what the Product Manager wants, and what the
engineers/developers are going to do to address those wants.
The other category of documents is the project-tracking doc set.
Those can have all kinds of names as well. There are overall project
timelines and the subsidiary timelines (of each group or person) that
fit into the overall project timeline. There are formal milestones (we
call them DRs 1 through 6 (Decision Report phases) during which the
various other documents and tracking materials are brought together,
forced to a certain state of progress (much use of whips and cattle
prods in the week or two running up to a DR) and major sign-off-age
happens.
There's no simple standard for this stuff, because it depends on the
scope of the company and the product and the project and...
So, at our place, the progression looks like this (quoting my Veep):
DR1 - Concept - meaning the Product Manager is still trying to prove a
product (or release) is a good business idea
DR2 - Definition - meaning the development manager and others are
planning a development and release of the product
DR3 - Design & Verification - aka development and Eng test - where all
the *real* work gets done
DR4 - Validation - SQA and production qualification - where we realize
it doesn't work yet
DR5 - GA - it finally works and is orderable by customers (without
needing to send an Engineer in the box)
DR6 - End of Life for the product.
Each group that has any involvement might have its own documents and
internal processes, and certainly has its own resource constraints and
schedules. As much as possible, we're trying to make the documents that
are internal to a group also be the docs that do up to the Project
Planning/Management level (for all those DRs) so as to avoid duplication
of effort and to have us ready for ISO certification next year.
The development portion of a project might take place here (Ottawa
Canada, branch office) and in India (another branch office). Elsewhere
in the world for other products that I don't happen to touch... The
engineering testing might take place in either or both places, and the
SQA would take place at headquarters in Maryland. The production
planning, creation of work instructions, manufacturability testing, etc.
would take place between headquarters and one-or-more contract
manufacturers. We still make a lot of use of SharePoint while our shiny
new ERP system is being rolled out. We're constantly working to slim
down the load of documents while making them as useful as possible to
all parties.
All of that, and only two words about what I actually do, which is
customer-facing documents (and filling in of my little portion of the
project docs, as they come through my inbox).
OH! Oh!oh!oh!oh! and OH! I forgot. The most ubiquitous and possibly
most useful of the in-house documents that we see all the time: MEETING
MINUTES and revised PROJECT SCHEDULES. What are people doing? What's
missing so they can do what they need to do? Which activities are
complete? Which ones are slipping? Who's got what action items?
My former boss, who took on project management for local product lines,
is _very_ good at this stuff. And at the people-herding that makes the
timelines tick along. And at adapting, on-the-fly, when yet-another
monkey-wrench gets tossed into the works.
I was going to say "but I digress"... but this whole thing is a
digression, isn't it? :-)
Cheers,
Kevin
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
