RE: Collaborative tool for readme writing

Subject: RE: Collaborative tool for readme writing
From: "Blount, Patricia A" <Patricia -dot- Blount -at- ca -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 18 Apr 2008 08:47:17 -0400


Good morning and my apologies if this reply comes too late to be of much
use. I'm on the digest.

I just finished a lengthy Readme project and (still) suffering through
the same headaches you described in your post. What bugs me is that we
have a fairly strong process that we simply cannot enforce.

We're using AuthorIT to produce readme docs in HTML that's posted daily
to a network site and picked up automatically by the build process.
Development folks open issues to report changes or corrections needed
and I am responsible for managing that queue. Additionally, a Word
version is posted on another network share for non-Dev folks to
review/contribute changes.

They are supposed to work directly in the Word file, using Track
Changes, but invariably end up making local copies of the file and
emailing it to me.

Here's what I ended up doing before I jumped from the roof of my
building. It ain't pretty, but it works.

>From day 1 of the effort, I took a snapshot of the AIT source published
to Word and stored that on my local drive. Each and every issue, email
or change request that comes my way...I make in two places - to the Word
file and in the original AIT source. Yes, it's double the work. However,
in the Word file, I also note the issue number, the email date and who
sent it, etc. with Track Changes.

This method has been invaluable to me because no sooner do I make a
change when another reviewer is asking me why something was deleted. I
can simply look up the initiator, direct the offended party their way
and let them duke it out until they're both happy.

Interestingly enough, it does not take much time to do this, which
surprised me. I really thought, "Wow. Double work, twice the time." But
as I write in AIT, I merely copy and paste the change into the Word
file, note the source information and save. I can publish a clean copy
in HTML or Word any time I need to from AIT because there is no
'garbage' there. It's all in my local word copy.

Like I said, it's not elegant. If anyone comes back with a cleaner
suggestion, please send it my way... :)

Patty B.

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

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

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Tim - Levels of Edit
Next by Author: RE: How many TWs...
Previous by Thread: RE: Collaborative tool for Readme writing
Next by Thread: RE: TECHWR-L Digest, Vol 30, Issue 17

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

Sponsored Ads