single source tool eval (summary - long)

["Carol Chung" <cychung55 -at- hotmail -dot- com>]

Hi, I'm sending responses to a request for comparisons between single-source 
documentation tools (framemaker/webworks, doc2help, arbortext, and 
author-it). Included:

1. criterion for tool eval
2. tools considered
3. email responses

HTH, Carol (plan to recommend doc2help because of shorter source document 
size in Word format and ability to share source across dept's)
---

Criterion:

	-functionality
		-ability to tag content for forms of output
		-flexibility of output
		-globalization

	-price

	-ease of use
		-time to learn usage
		-importing existing word docs
		-ability to share sources w/ other depts?

---
Tools considered:
	-doc2help pro 2000
	-framemaker/webworks
	-author-it
	-arbortext: said pricey

---
Email responses:

There is a tool on the market that I think you will find extremely useful -
AuthorIT. Its a single source documentation tool that allows you to generate
multiple outputs from a single source. At the moment the software is at
version 3 and allows the following generations: Word, HTML Help, HTML Pages,
Winhelp, JavaHelp, Oracle Help and XHTML - All from a single source. A PDF
can easily be generated from the resulting word file with minor tweaking.

This is an extremely powerful tool and follows the Object Oriented Model of
documentation. It also allows multiple users to work concurrently.

I could carry on writing about the pros of using this software (I am not
affiliated with the company, just an extremely satisfied customer) but its
all on their website: http://www.author-it.com

You can also download a free evaluation edition from the site.

Without the intention of starting a tool war, I will say that this is by far
the best software I have ever come across for a professional Technical
Writer and once you've used it you'll never turn back.

Meir
meirf16 -at- netvision -dot- net -dot- il

---

Hi, Carol.

No quick references here, but I can give you my admittedly biased opinion.

   1. Framemaker/Webworks


I use this combination exclusively for single-source content development,
and I'm coauthor of the *WebWorks Publisher Cookbook*. This set of tools
will give you the most flexibility. There's almost nothing that you can't
customize in your output. That said, you have to be ready to tag your files
very consistently and adopt a more structured approach to your content
development if you want good online help and good printed documentation.
The tool also has a learning curve, but you can progress quickly if you
take a class somewhere. (It doesn't hurt to have our book either.)

BTW, the book features in Frame are far superior to anything in Word. You
get autogenerated lists of reference, tables, and indices, cross-references
that are live in PDF and HTML output, and conditional text features that
allow you to maintain multiple versions of a document in one file.

   2. Doc2Help


I've converted files out of Doc2Help for the simple reason that it's too
constraining. It also had poor support for localization (which might have
changed in more recent versions). I just find it a clunky tool to work
with. However, if you don't want to convert your legacy documentation and
can't afford a hefty layout, this might be the way to go. If you have large
printed books, I'd go with Frame/WWP over Doc2Help. If you're only
producing help files, I'd go with ForeHelp or RoboHelp before Doc2Help. I
just don't think it's a very robust tool.

   3. Arbortext (Epic?)


Unless you have tools that can render XML into other formats, I'd stay away
from Epic. If your company has the cash to invest in a major publishing
system (say $70K+), then it would be great. However, Epic by itself only
creates XML. You then have to transform that markup into something else
(HTML, PDF, RTF, or whatever). It's a markup tool rather than a layout
tool. If you don't currently have someone who understands what SGML is all
about, this would probably not be the route to take. It takes a lot more
than just the Epic Editor to produce your books or help systems.

Most companies that use tools like Epic (or its predecessor, Adept) have
databases of document content. They can reuse pieces of that content in
various publications. When it's time to generate a product, they pull each
piece into a sequence (called composition), send it through some kind of
rendering engine (like an Omnimark script to generate PostScript, HTML,
RTF, or something), and you get your document. It's really a huge
undrtaking to put the whole system in place.

BTW, Epic's predecessor, Adept, was well known for its tendency to crash. I
don't know if Epic is more robust.

Let me know if you have any other questions.

Bill Burns, Director - Northwest Office, Scriptorium Publishing
The WebWorks Publisher Cookbook now available
http://www.scriptorium.com/books/wwpcookbook.html
bburns -at- scriptorium -dot- com - 208-484-4459

---

FrameMaker & WebWorks Publisher rocks! (Of course this is a highly biased
remark.)  ;)

For info on FM and WWP, check out the following:

http://www.wwpusers.com
http://groups.yahoo.com/group/wwp-users

I also have an aging paper that covers the basics of this combo:
http://www.geocities.com/bill_swallow/singlesource.html

*****************
BILL SWALLOW
Technical Writer
C O U R I O N   C O R P O R A T I O N
1881 Worcester Road
Framingham, Mass.  01701
T E L * 508-879-8400 x316
F A X * 508-879-8500
www.courion.com

---

Hi Carol
One could classify Doc2Help as a more basic tool as compared to FM and WWP. 
With
Doc2Help, you would really need to do a bit of tweaking. Though it is
inexpensive, it has a limited functionality and there will be a compromise 
in
both mediums.
The advantage of using FM is that you don't have to maintain a database or
purchase special tools. The disadvantage is that all you can do is turn 
elements
on or off.
Though I don't now much about Arbortext, there is another tool called 
AuthorIT
which is purely a single sourcing tool. It allows you to convert to seven
different formats at the click of a button.

Regards
Neelam
neelam -dot- singh -at- oracle -dot- com

---

Hi Carol,

We like Doc-to-Help because:

It's based on Word, which allows us to use the same software as everyone
else in the company.
It generates all of the outputs we need from one file: printed, help files
of all flavors, html, and (with the addition of Adobe Acrobat) PDF files.
It has conditional text so you can color-code sections for print-only,
help-only, etc.
It comes with handy shortcuts and templates that are nice.
People from Robohelp shops that come here have stated that Doc-to-Help is
more single-source than Robohelp.

Good luck,

Lindalee
Lindalee -dot- Brownstein -at- ebancllc -dot- com

---

I had a terrible experience with Doc-to-help.
It was very difficult to use, and blew up all the time.
Creating indexes was a mysterious and painstaking process.
But that was 5 years ago.
I suspect it has been improved, debugged since then.

Back then, I changed to HDK (which also runs on top of Word) and loved it!
I'm still using HDK.

Susan Jelus
Research Computer Services, Inc.
Dayton, Ohio USA
Susan -dot- Jelus -at- DaytonRCS -dot- Com

---

Carol,

You might find the attached article of interest. Our solution followed a
"single source" methodology to resolve issues of equipment and language
applicabilities from FrameMaker+SGML files.

Whether you need a database depends on the volume of files you need to
manage. In terms of processing your output, a structured approach (e.g.,
XML, SGML) is more reliable than depending on styles (e.g., plain
FrameMaker); but you need to consider document conversion costs and the
requirements to build your DTDs or schemas.

Hope this little bit helps.

Bill Hall
Documentation Systems Specialist
Data Quality
Quality Control and Commissioning
Tenix ANZAC Ship Project
Williamstown, Vic. 3016 AUSTRALIA
Email: bill -dot- hall -at- tenix -dot- com
URL: http://www.tenix.com/


---
"Barb Kowalik" <bkowalik -at- iknowledgeinc -dot- com>

Hi,
Sorry for the delay in emailing you -- mad documentation crunch.....
I am responding directly as I get the digest.
You wanted some comparisons. I had to respond -- even if I am late.

In my previous job, I used FrameMaker and WebWorks, in my current job I use 
Doc-2-Help
Why? Different tools for different needs. I love them both.

FrameMaker is a great tool for long documents. It does multiple chapters and 
it can easily be used to customize manuals when the software you document 
has multiple modules leading to multiple variations for the client. We sold 
patient tracking software and we had 6 different configurations that 
hospitals could buy. Each site got their own set of manuals (over 400 pages 
for the user guide and 350 for the admin guide) and own on-line help. The 
total pages - if someone bought the whole thing would have been around 750 
pages each.

Currently I work for a firm that develops software for asset management for 
media. It involves a lot of SDK and API writing and short sets of 
documentation for products created by our service group. When I started they 
had gone from being part of a large media company to spinning off into a 
separate smaller development company. the original documentation for the 
first product was highly technical - over 2000 pages and no one ever read 
it. I did a lot of research and talking within the company. As we have 
trainers that go to client sites around the world, they wanted documentation 
that they could update on the fly and marketing wanted to be able to extract 
sections for their needs. Development was creating the Use Cases and UML 
documents and White Papers in Word and our tools are Java or com based-so 
the on-line help needed to be in compiled HTML or Java.
The word processing tool of choice was MSWord. That left me with RoboHelp 
and Doc-2-Help.

Having worked with both those tools before and found both of them adequate I 
downloaded the evaluations and created essentially the same documentation 
with both (2 different clients so there were minor changes but both worked 
out to about 70 pages).
Doc 2 Help won hands down. The interface is less confusing and even those 
who have had no experience with creating documentation have been quite 
surprised at how they can use it to create an HTML file.
I created a new documentation template and tool bar using the correct 
styles. I shipped to all of those that needed to look at, create or change 
the documentation in Word and we have had few problems. Their documents can 
be imported into mine and the dreaded Table problems between Word97 and 
Word2000 have been eliminated.
Doc-2-Help's price was not prohibitive and the support is great.
In my last experience with RoboHelp, my boss was upset that they released 
upgrades every six months, that there was no discount for repeat customers 
and he could not get the word docs to display properly. I did not like all 
the fiddling I had to do with the RTF file to get the Help to work properly.

So, If you are counting a poll ...
For Long Documents, or Documentation of multiple modules that can be 
combined in different components, FrameMaker wins hands down.
For documentation under 100 pages (a Word Limit), sharing documentation with 
other departments and creation of multiple formats of on-line help - its 
Doc-2-Help.

My Opinion
Barb

"Typo? What tpyo?"

---

Carol,

FrameMaker integrates very strongly with Adobe Acrobat. So strongly
that all hyperlinks in FrameMaker are translated into links in PDF.
That makes tables of content, indices, cross-references, markers of
many sorts, clickable links in PDF. Very strong navigation. All from
the source.

WebWorks is a thrid-party program, but is very strong when going to
HTML, or even WInHelp from FrameMaker.

Scott
quills -at- airmail -dot- net
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


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