RE: Gift for those single-sourcing or API documentation projects

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

> -----Original Message-----
> From: Andrew Plato [mailto:intrepid_es -at- yahoo -dot- com]
> Sent: Wednesday, January 23, 2002 6:08 PM
> To: techwr-l -at- lists -dot- raycomm -dot- com
> Cc: Glenn Maxey
> Subject: Re: Gift for those single-sourcing or API documentation
> projects
> 
> 
> 
> "Glenn Maxey" wrote...
> 
> > I just uploaded a file (tp_tools.zip 1.8 MB) to the HATT 
> > files area that
> > may be of interest to those creating large single-sourcing 
> > projects or API documentation.
> 
> I downloaded it. It's a wealth of neat information. 

You must have discovered my rant in chapter one. :)
 
> > Comments and suggestions are appreciated. However, I must 
> > be honest that
> > I have enough on my plate and am trying to get these out so 
> > that I can
> > move on to other more pressing projects at work. There's no 
> > guarantees
> > that I'll do anything further on the tools themselves. 
> 
> Which leads to my comment...you had enough time to write all this? The
> user guide alone is 118 pages! That's a heck of a lot of one-off work,
> Glenn. 

Well... I have had the tools working for some time now and used them on
several projects. Because I'm a technical writer and not a programmer, I
put just enough comments in my code so that I could figure out what I
was doing. My goal was just to get the tools finished so that I could
complete my objectives.

My co-workers were bugging me to document them with better comments,
etc. in case I get hit by a bus (a very realistic possibility for those
of us like me who try to use public transportation.) They certainly
could have made do with with the 5 page version along with code
comments.

I made the suggestion and sent it up the corporate flagpole that I be
allowed to open-source them. Afterall, tech pub tools isn't our
business. Moreover, I used open-source tools (Doxygen) in my solution,
as have other areas of the company. When broached at a staff meeting, my
co-workers re-enforced to our manager my views that the tools could be
open-sourced.

The idea of open-sourcing them (to a primarily tech writing audience)
inspired me to "eat my own dog food" by using the tools on themselves,
demonstrate what they could do, and create better documentation than
what was required. (It is still not perfect, and I make no such claims.)

Also, our marketing department tends to get lots of awards for things
they do. We in tech pubs can't always submit what we've done to
competitions due to the proprietary nature. Our manager and his manager
liked the idea of tech pubs getting some recognition from our peers.

 
> Thanks for the work, but man, if my employees had enough time 
> to do that I'd find some billing work for them. 

Given my motivation, I was able to work diligently over Christmas and
New Year when otherwise it would have been deathly slow and boring at
work. You know how it is when you get a chance to work on "your own
stuff." Time just flies by and those last two hours after normal working
hours are the most productive.

And... I got a chance to revisit my various rants that were written to
various newsgroups, consolodate and edit them, and include them in the
doc's. :)

Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for only $299, through January 31st. RoboHelp can import your
existing Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr

---
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.