Object-oriented Doc tool: AutoDoc (LONG)

[Matthew Bin <mattbin -at- HOTMAIL -dot- COM>]

This is to follow up my last post, in which I tantalisingly mentioned
that I was looking at an OO documentation tool, but failed to reveal
which one in particular.  Let the mystery dissolve here!

I am currently evaluating AutoDoc, by Optical Systems Corporation in New
Zealand.  Their home page is

http://www.oscl.com/

AutoDoc is really a front-end for a hidden relational database.  For
users familiar with object-oriented programming languages (such as, in
my case, SQL Windows by Gupta), this is a typical object-oriented
environment.

AutoDoc allows the writer, through a fairly intuitive GUI, to create
Word, On-line Help, and HTML documents simultaneously.  Don't want that
topic in the help?  Un-check the box.  Want it in a secondary window?
Or a popup?  Click on the radio button.  All the messy crap is handled
competently by AutoDoc, which is great for a generally dense sort of
user such as myself.

AutoDoc will output to HTML, Word, or WinHelp.  You can select which of
those any particular object appears in.  (This is much easier than the
marked text approach I've seen in Doc-to-Help.)

Perhaps I ought to insult the intelligence of the list by explaining at
dreary length what "object-oriented" means in this case.  Each item in a
document, such as a title page, a table of contents, a paragraph style,
an inline graphic, a topic, or whatever, is an object which rests in the
database.  Your document is really a series of links to the objects
you've put together; AutoDoc organises these graphically in "books",
where all the objects are displayed in a format similar to Windows95's
Explorer.

Why bother, you ask?  Well, there are a few good reasons I found for
myself.

1. Re-use of text.  A standard title page or copyright notice need never
be changed again.  It's much easier to drag-and-drop the object than it
is to copy it from an older document or whatever your personal strategy
is.  What's more, because every document is linking to the same object,
update it once and you've updated it every time, without fail.

2. Inheritance.  If you don't want to re-use an entire object, but you
want its properties and so on, you can make a template on which to base
many objects, or even better, you can copy one object and

3. Ease of juggling.  Forget the master document feature.  Forget all of
the word processing solutions to re-organisation ever developed.  There
is no better way, in my opinion, of dealing with re-organisation than
dragging and dropping and demoting and promoting objects visually.



Disadvantages I have found with AutoDoc:
----------------------------------------
1. Slow learning curve!  Although I am not entirely new to such
environments, I had to ask a number of very stupid questions of OSC's
people.  These questions could have been answered with a closer reading
of the Help file, but I knew it all and couldn't be bothered.  (OSC
always answered quickly and politely, never pointing out my
stupidity--see advantages #1.)

2. Bugs.  I don't want to scare anyone, but no, AutoDoc is not perfectly
bug-free.  (Unlike, oh, say, Word97, right?)  However, OSC's support was
as usual top-notch, explaining what had happened and quickly sending a
patch to solve the problem.

3. Limited authoring environment.  This just ain't a word processor, not
a real one anyhow.  However, it is very customizable, including
user-defined toolbar buttons and so on.  Furthermore, it is no more
limited than any other stand-alone HAT I have examined.  Less if
anything.

4.  Not yet compatible with Word97.  However, a Word97-compatible
version will be out this spring, I am told.

5.  It's not that easy to convert existing documents to the AutoDoc
mode.  AutoDoc will convert your old documents for you -- for a price,
of course.

6.  I anticipate that many experienced help developers would feel
constrained by AutoDoc's "I'll handle this" attitude to generating the
help.  I'm not sure how hard it is to do the fancy Help stuff in
conjunction with AutoDoc.  (For Simple Simons like myself, this isn't an
issue.)



And the Advantages:
-------------------

1.  Excellent support.  These people have been one hundred percent
top-notch, which is more than I can say for any other company I've had
to deal with.  (Maybe other people like Adobe, but I am not impressed
with their support or sales people.)  I get immediate, personal, polite,
useful responses to any enquiries I have, and many offers of additional
help.  I realise that it's easier for a small company to provide good
customer service than a large one, but great service takes work, and
boy, OSC works at it!  (By the way, I haven't paid a cent to OSC yet.
This service has all come for free--take that for what it's worth, of
course.)

2.  Great interface.  Once you learn how to use it, the AutoDoc OO
environment is as powerful as any doc tool I've seen.  (Take that as an
utterly subjective opinion, of course.)

3.  Flexibility. Remember a few weeks ago, when the topic of a generic
proposal came up on this list?  Well guess what I did for writing my own
proposals!  AutoDoc lends itself to this sort of flexibility.  The
re-use and inheritance make changes and updates quick and painless.

4.  It does what it says.  As far as I can see, links and
cross-references always work, things always show up where they're
supposed to.  Generally a solid piece of software.  I do not cry or
gnash my teeth, as I often do with Word.

AutoDoc costs $549US for a single-site license (I think $795 in New
Zealand bucks).  This includes a installation support, and technical
support for six months after the next major version release.

AutoDoc can be downloaded at the OSC website, or from ZDNet, the
Shareware download place (where AutoDoc earned a four-star editors' pick
award).  It's about 8 megs long.

Well that's about it.  I encourage you to download AutoDoc and give it a
good look.  If this isn't where documentation is headed, I'll eat my
hat.  If you don't believe me, look at how many people still program in
linear languages like BASIC, and how many people program in
object-oriented environments like Visual Basic!

If anyone has any questions about AutoDoc that I failed to answer here,
feel free to ask!





Matthew Bin
Technical Writer
NeoDyne Consulting, Ltd.
Mississauga, Ontario, Canada


______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com