Re: Online Help Style Guidelines

[Susan Gallagher <Susan_Gallagher_at_Enfin-SD -at- RELAY -dot- PROTEON -dot- COM>]

Laura Zupko asked the following questions about creating online help:

>I wanted to get some opinions/information about style guidelines
>for online help systems:
    >1)  Has anyone created or used online help style guidelines and
    >just how useful were they?

    We, as a company (Easel Corp in MA and Enfin Technology in CA), have yet to
    develop an online help style guide, but we certainly see the need for it.
    It's difficult enough to keep consistent from screen to screen, much less
    from one product or application to the other.

    >3)  What type of information do you think online help style
    >guidelines should include?

    This depends on the type of product you're developing help for and the
    platform(s) on which it runs.  Basically, you'll need to decide some or all
    of the following:

    *Will you construct one topic per dialog box or document to the field level?
     If you construct to the dialog box level, in what order will the
    information be displayed (general to specific, left to right, up to down...)

    *If you construct to the dialog box level, how will you handle dynamically
    created fields?  How will you handle topic levels (indenting is pretty much
    ruled out when you're writing for such a small space, italics are out
    on-screen, color is only good if you're confident that users will all have
    the same hardware and nobody's using "hotdog stand")

    *How many levels of hyperlinks will you need?  Should hyperlinks go at the
    beginning of the topic or at the end?

    *Will you use font changes?  Bitmaps?  When... Where??

    *Are you limiting the information to context-sensitive stuff, or will you
    include procedural info, too?  How will you handle this?

    The number of questions your style guide should/could answer is almost
    limitless.  I attended a Communitec seminar last spring that suggested
    developing templates for the different types of information you plan to
    include.  This sounded like a worthwhile approach, but I haven't had a
    chance to put it in to practice yet (where does the time go???).  BTW, there
    are several good seminars on developing online help that will help you get
    off to a good start.

    >4)  Has anyone used OS/2's Information Presentation Facility (IPF)to create
    >online help?

    A major thorn in my side is that "my" application runs on OS/2, Windows, and
    Unix (almost seamlessly).  This means that I need to create a single source
    file from which I can generate "native" help for all three platforms (wadda
    b**ch!).  OS/2 and Windows help utilities have a whole lot of subtle
    differences that you need to be aware of before you start.  For example...

    *OS/2 does not handle pop-up definitions elegantly.

    *OS/2 builds its table of contents dynamically from the heading levels
    assigned to topics and the order in which they appear in the file.  This can
    be a real bear to cope with because Windows doesn't care what order the
    topics are in, so the Windows based apps don't provide utilities for moving
    topics around.

    IPF's only saving grace is that it's lots easier to read/edit manually than
    RTF is.  Maybe it's just the lack of curly brackets that makes it seem so.
    IBM does provide good hard copy reference for IPF -- something that
    Microsoft doesn't do for RTF.

    Other things you need to consider (as you do with paper doc) is whether
    you'll push, press, or click on buttons, and all the other good stuff that
    goes along with writing consistent and usable doc.  These (as they evolve)
    will find their way into your style guide (or migrate themselves from your
    paper style guide to your online style guide).

    Last word of advise, before you start...  PLAN... PLAN... PLAN!!!

    I'm out'a here!

    Susan Gallagher @ Enfin-SD