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:"sbuckley" <sbuckley -at- onlinewriter -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 21 Sep 2006 13:18:21 -0700
It sounds like what the VP is really asking for is a tracking mechanism. If
the spec process is already set, a good mechanism is bug tacking in programs
like Bugzilla, Raid, and TestTrack. As others have mentioned, having a
specific field for UI changes is great, but only if you can get people to
remember to use it (and I found that to be difficult with some groups).
To keep Help docs updated, I used email reports of new bugs, just checked
for new bugs everyday, and/or attended meetings called to decide which bugs
to fix. The following round the specs were then updated with the last
excepted bugs.
I was also involved with a group that, instead of creating one or two large
specs for a project, created a specific spec for each specific feature. At
first, the amount of specs seemed overwhelming, but overall it proved very
helpful. It was easy to tell who owned which features, which features had
been cut, and which features had been recently updated.
-----Original Message-----
From: techwr-l-bounces+sbuckley=onlinewriter -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+sbuckley=onlinewriter -dot- com -at- lists -dot- techwr-l -dot- com] On
Behalf Of Dan Goldstein
Sent: Thursday, September 21, 2006 11:51 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Engineering specs: The way it spozed to be?
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 sbuckley -at- onlinewriter -dot- com -dot-
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-
