RE: Technical Documentation solutions?

Subject: RE: Technical Documentation solutions?
From: "Lakritz, Andrew M." <Andrew -dot- Lakritz -at- Ruesch -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 27 Aug 2002 11:02:55 -0400


In my shop we have been making progress toward getting the technical
documentation of software systems closer to the bone, that is, in the
software itself (in our case, that means in the database where much of our
business logic is encapsulated). I do a lot of writing in the stored
procedures themselves, as well as in the extended properties of the tables
(MS SQL Server 2000). The documentation, then, can be generated rapidly
(about 4 hours) using tools I have to parse the code and the other database
objects and produce a CHM file (which I don't use except as a go-between for
WebHelp) and a WebHelp Web site. I use Document! X and RoboHelp 2002 for the
automatic generation. That way I don't need to fiddle with the configuration
more than once, and I can generate a new Web site every week to keep up with
development. Our engineers are encouraged to document all of their new
stuff, using the same tags and techniques I use to document that 3 or 4
thousand older objects that do not have tagged comments. There is nothing
automatic about this content creation: the writer still has to write the
comments, by hand, object by object. Creating the Help Web site is
automated, however, which makes it possible to progress toward the goal of
having all of the most important software objects fully documented, from
week to week.

None of this would have happened without a technical writer being the lead
and working with the senior software architects to ask the right questions
and making it happen.

I have heard senior engineers in other shops tout Java as one way to
eliminate technical writers. I don't see it happening. I have not seen it
happen anywhere.

Regards,

Andrew Lakritz

-----Original Message-----
From: Sean Brierley [mailto:sbri -at- haestad -dot- com]
Sent: Tuesday, August 27, 2002 10:43 AM
To: TECHWR-L
Subject: RE: Technical Documentation solutions?



I am surprised nobody else offered an opinion on this. Clearly, it doesn't
rise to the level of one versus two spaces or FrameMaker versus Word, but is
there no thoughts, offerings, or opinions on:

1) Automatic creation of content.
2) Technical writing without technical writers.
3) Technical writing duties not affecting the core responsibilities or time
of SMEs, engineers, analysts?

Maybe my thoughts are offbase. Say, is the subjunctive appropriate for a
user guide written in the third phase of the moon using Volkswriter?

Cheers,

Sean

-----------------------------------------
Sean Brierley
Software Documentation Specialist
Haestad Methods
http://www.haestad.com
203-805-0572 (voice)
203-597-1488 (fax)



-----Original Message-----
From: Sean Brierley

Nope. Engineers want to engineer. They enjoy it. Analysts want to analyze.
They enjoy it. Team leads want to lead. That's their thing. And the manager
likes his coffee with two creams and three sugars. But, none of these guys
are about technical writing. It's not what they signed on for, it's not
interesting to them, and it takes away from their primary duties.

It's a blood from a stone thing. If you need content to get written, you
cannot add that to the chores of an existing workforce and expect no affect
on their day-to-day core jobs.

Get back to us in 6 months and tell us what happened. Sounds like you can
get some neat verbiage for your resume, though.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at http://www.ehelp.com/techwr-l

TECHWR-L is supported by ads and sponsorships...and donations.
You can help maintain the TECHWR-L community with donations
at http://www.raycomm.com/techwhirl/abouttechwhirl/donate.html

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



Previous by Author: RE: Help - I/T Library
Next by Author: RE: Technical Documentation solutions?
Previous by Thread: RE: Technical Documentation solutions?
Next by Thread: RE: Technical Documentation solutions?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads