TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
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?
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
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.