Word Master Documents or RoboHelp - Are either usable for modular documentation?

Subject: Word Master Documents or RoboHelp - Are either usable for modular documentation?
From: Ed Manley <EManley -at- Solutionsplus -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 14 Feb 2002 11:32:38 -0600

Hello techwrlers, here I go again with a slight twist on an already-asked
question.

Thank you all for your input.

I am having these conversations in multiple forums and plan to combine all
of my findings, the processes and tools that they lead to, as well as a
detailed description of my implementation, for publication on a web site
that I will build for modular documentation methodologies in the near future
(for free access). There has to be a better way to do software development
documentation without spending a fortune or throwing the whole company for a
loop - and I intend to find it!

I am in search of help from people experienced with software technical
documentation (or any form of structured writing or modular documentation)
using either RoboHelp or MS Word (MS Office).

The principles of write-once hyperlinked modular documentation (though its
not called that) used in creating on-line help with WinHelp/RoboHelp and the
"chunking" and team-collaboration aspects of Master Documents in Word appear
to fit right into my needs, but I am not sure where roadblocks lie, and so
seek guidance and opinion.

As mentioned in previous posts but provided here for background, I am in
search of a better way to "do" documentation for software development. We
currently use the same structured Word docs that have long been used for
waterfall software development - the various Requirements and Specifications
docs, User Guides and what-have-you, and find now that we are outgrowing our
ability to maintain them.

I am looking at modular documentation methods, and at topics such as
structured writing, object-oriented documentation and others, that might
give us the ability to write once publish many, write topically-focused
documentation, eliminate formatting issues for the writer, allow for instant
update of repetitive info across docs and so on.

Though we use only a few templates, perhaps a dozen, to spawn all software
documentation, we may have many instantiations of any one those docs
(perhaps thirty Functional Specs in play at any given time for thirty
product enhancements underway). A screen shot or a file layout may exist
pasted into any number of those docs. If the screen changes for a release
then all of those docs containing the image must be found and updated.

Can I use RoboHelp or Word Master docs to build virtual documents, where
most every element in the doc is in fact a link to a single object (file) on
a shared drive?

Then I could make a change to that image and every document that references
it would be updated. This, I think, is what RoboHelp does when creating
online help. I would think that the RoboHelp Documentation Wizard that
allows me to print on-line help would be perfect - but I am told it won't
work, though no evidence has yet been presented either way.

I know there are content management systems out there that purport to allow
this, but all of them I have seen are very expensive.

My research into XML DOCBOOKS and XML Schema and tools of that ilk indicate
a cost-of-implementation barrier that I don't think I want to address unless
I absolutely have to, so I continue to look for methods that allow me to
leverage the knowledge, skills and tools that I already have at hand, or can
afford to adopt.

What can we do along those lines using either RoboHelp or Word Master Docs?

I have played with Master docs occasionally through the years, without
impressive result. Perhaps that's because of a high file-corruption rate,
perhaps because I haven't learned enough about the tool...regardless, I
still fall back on my basic desire to use the tools we have to solve these
problems, which, I think, means Master docs...or RoboHelp? Or what?

Any suggestions?

Thanks,
Ed



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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: Author-it, Learning curves and base practices
Next by Author: Re: Tired of Giving Free Advice
Previous by Thread: RE: zip TM query
Next by Thread: Simplified English anyone??


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

Sponsored Ads


Sponsored Ads