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.
Subject:RE: Engineering specs: The way it spozed to be? From:"Dan Goldstein" <DGoldstein -at- riverainmedical -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 21 Sep 2006 14:51:18 -0400
Very broadly, I'd distinguish between revising a document (updating it
to reflect reality) and releasing a document (making it an Official
Thing -- "freezing" it).
Manuals are released to end users according to your company's unique
needs -- Help desk, marketing, etc. The same goes for releasing an
official spec: "This is now version 5.3.0 of our software. Bask in its
glory."
However! Followed by many exclamation points!!! A big part of our job is
to make sure that somewhere, under our control, there's a document
that's up to date. Revise it, control it with version numbering, back it
up, and make sure it has a nice glass of milk before bed.
What you're trying to avoid is that last-minute panic of trying to
revise a document to reflect all of the changes that have taken place,
undocumented, since they last released the documentation (i.e., during
the Hoover administration).
In other words, *all* changes should be written down.
In an ideal world, the engineers revise the spec before they change
stuff. In *your* world, the VP doesn't even expect them to revise the
spec *after* they change stuff! All you can do, to the best of your
ability, is to keep safe revisions of the end-user documentation and the
spec (yes, that too).
Of course, you should also make your documents useful and available to
everyone. Be friendly, be organized, and you may yet subvert their
chaotic culture until they see the virtue of your ways.
-- Dan Goldstein
> -----Original Message-----
> From: stevefjong
> Sent: Thursday, September 21, 2006 2:32 PM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Engineering specs: The way it spozed to be?
>
> (The title is with apologies to James Herndon...)
>
> The VP of engineering at a startup has asked me to help
> implement the engineering specification process. What a
> wonderful opportunity to set things up the way they're
> supposed to be! But the question is: What IS the way things
> are supposed to be?
>
> This company has a wiki, and it's culturally well
> established. Engineers are conditioned to put their documents
> in the wiki. There are only a couple of externally visible
> documents, done in (bleech!) Word. The next release is
> whenever the next client signs up. Right now, there's no way
> to tell if a document on the wiki describes the present, the
> future, or the past. The daily change log reveals that, as
> far as I'm concerned, the engineers update documents at random.
>
> Paraphrasing the VP's concern: "I don't expect you to update
> the end-user documentation every time the engineers make a
> change. But I don't want them to update a spec every time
> they make a change, either. What is the triggering mechanism?
> What changes should be written down, and when? I want you to
> answer that question."
>
> This is a wide-open situation. I have my own ideas, but I'm
> interested in the theoretical question too. If you could
> offer any solution, what would you suggest?
>
This message contains confidential information intended only for the use of the addressee(s). If you are not the addressee, or the person responsible for delivering it to the addressee, you are hereby notified that reading, disseminating, distributing, copying, electronic storing or the taking of any action in reliance on the contents of this message is strictly prohibited. If you have received this message by mistake, please notify us, by replying to the sender, and delete the original message immediately thereafter. Thank you.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
