Re: Doc for multiple interfaces

[David Blyth <dblyth -at- QUALCOMM -dot- COM>]

>I am seeking advice and alternatives for documenting the same product that
>runs in multiple interfaces.

I worked on a similar project several years ago with a group at
another company.

>We are already writing what we call "interface-independent" doc, in which
>we don't discuss interface specifics for commands.

Our group split the docs into three types

  o 100% Interface-independent. This idea worked very well and the more
    interface-independent docs we could make, the better.

  o Docs with conditionals.

    One doc I worked on was actually split into two different CM
    numbers.  Part I was independent, Part II contained conditionals
    and was assigned a different CM number each time we released.

  o Platform dependent docs.

Our group also split human resources into each category.  I handled
completely generic stuff, and other writers were split into conditional
docs or platform dependent.  We occasionally switched off.

>   Produce a separate doc for each style of screen?

    This worked fine under "Platform dependent".  We did
    try to group things where we could, or reduce things
    to least common demoninators (CLI?).

>   Produce one doc that includes all styles of screens?

    I think we tried this once and it was a complete bust.
    The doc was too messy and it was easy to get confused
    between which interface was discussed.

>   Pick one style of screen and produce doc using it, not showing others?

    I'm not sure if we tried that or not.  It seems like it would
    only work if the features were the same across all interfaces.

>   Produce doc that does not have any screen images?

    This worked great for docs that didn't _require_ any screen
    images.  For example, I worked on a Ref Manual to move it
    from "Platform specific" to "Conditionals".

    A lot of what worked for us was redesigning the doc set to
    shove common stuff together.

    It also helps if you can get marketing or engineering to
    start designing Web stuff that looks similar to Windows
    (or perhaps vice versa).  This tends to reduce the work
    load for everyone, because only one interface is used.

    But once a doc _required_ screen shots - and the images varied
    between the Web and Windows (or anything else) - then we were
    better off using conditionals, or giving up and making the doc
    platform dependent.

    And if your DTP doesn't provide conditionals, then you really
    do need to consider buying one that does.

I didn't mean this to be so long.  Hope this helps.



David (The Man) Blyth
Sr. Technical Writer
QUALCOMM - Standard disclaimers apply.  They don't represent me, I don't
represent them.

Blodo Poa Maximus
-----------------

PS.  Only the "Maximus" is Latin

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html