RE: Engineering specs: The way it spozed to be?

["Joe Malin" <jmalin -at- tuvox -dot- com>]

My observations, based on a career as a software engineer and software
product manager:

* start by getting engineers to write up a short design/spec document,
including use cases,
  design decisions, comments, etc. A wiki is a great place for this;
that's what we use here.
* *Encourage* but don't *require* regular updates. See if you can get
RSS feeds from the wiki
* Perhaps schedule one or two milestones where the engineers update the
docs with new
  information.
* You (the tech writer) read the wiki before you start writing. Where
you find discrepancies
  between the product and the documentation, point them out. They may be
real changes that
  didn't get documented, *or* they may be bugs! I've found bugs that
way.
* Talk with the engineers. Find out what they think. Your expertise as a
tech writer includes
  *understanding your audience*. Your VP may think you're the expert on
setting something like
  this up, but your real talent is figuring out what your audience
wants.

Having used a bunch of web-based collaboration tools, I *strongly*
recommend wikis. If you (not Steve, but the audience at large) use
Windows/MS Office, and have a choice of a wiki to use, you might want to
look into a Windows-based wiki; many of them have the ability to view
and edit MS Office documents in place.

Joe

Joe Malin
Technical Writer
(408)625-1623
jmalin -at- tuvox -dot- com 
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.	

-----Original Message-----
From: techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of stevefjong -at- comcast -dot- net
Sent: Thursday, September 21, 2006 11:32 AM
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?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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- 

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.