Re: RoboHelp and documentation plans

[k k <turnleftatnowhere -at- yahoo -dot- com>]

> 
> Alicia Robinson wrote,
> >I see that RoboHelp has a feature that allows you
> to track topics
> >individually. (You can keep track of which topics
> are complete, which need
> >to be reviewed, generate project status reports,
> etc.)
> >Do RoboHelp users find this feature sufficient for
> tracking topics, or do
> >you additionally (or alternatively) use a written
> documentation plan?
> 

I've done many help projects, and I've never used the
tracking feature. As far as I can determine, that has
never hurt my work.

Noting which topics are in progress or finished is
pretty meaningless unless you can be sure that which
you are documenting is finished. If the product is
liable to change at any moment then the help system is
liable to change, and you can never really call
anything "finished" until the product goes out the
door. This is probably more true in documenting
software but is also true to some extent in
documenting other things.

Noting which topics need review is also meaningless,
because the help topics will probably never be
reviewed singly. In 99% of all cases, the topics won't
be reviewed in the Robohelp interface - the help
system will be reviewed as a compiled help system.
This is especially true of a review done by the
engineers or developers. In that case you may want
some way to visibly annotate the pages that require
particular attention by the reviewers, but they'll
never see the "in progress" marks in RoboHelp.

What about the other tracking selections? Things like
"Added to TOC," "Browse sequences," "Index" - most of
the things that can be tracked using those checkboxes,
you can see whether they've been done in the project
controls panes or in the topics themselves.

I figure it's more important for me to know quickly,
when I open a topic, what has or has not been done to
it. I use strings of placeholder markings that give me
immediate visual clues when I look at a topic, 
without diverting to the properties wizard. For
example, if I know that part of the topic content is
probably inaccurate and I have to get better
information from the SMEs, I preface that paragraph
with a string of exclamation marks (!!!). If I know an
area is incomplete, I mark it with question marks
(???). To indicate I think a topic is finished, I put
asterisks in the heading (***). And there are some
others that I use for various purposes. I use strings
of multiple characters because that way there's almost
no chance of confusing a placeholder string with a
normal use of one of the characters.

This has another advantage - it's quicker to find
information about the state of the topics than using
the tracking feature, which as far as I know can show
information about only one topic at a time. By using
the search engine, I can find exactly where I have any
placeholders, anywhere in the files. I have my build
checklist set up so that one of my standard steps is
to comb out these markings before regenerating the
help system. If I'm doing a preliminary build, I use
Dreamweaver to search out the placeholders and set
them in HTML tags to make them invisible. Then when I
get more input and need to go back to marked
locations, I can reverse that process and get the
placeholders back again. When I'm making the final
build that will go to the end user, I do a search and
replace that actually deletes the placeholder strings.



__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free web site building tool. Try it!
http://webhosting.yahoo.com/ps/sb/