Re: Doc for multiple interfaces

Subject: Re: Doc for multiple interfaces
From: David Blyth <dblyth -at- QUALCOMM -dot- COM>
Date: Fri, 25 Apr 1997 12:29:57 -0700

>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


Previous by Author: Re: Web Server & Documents
Next by Author: Favorite DTP
Previous by Thread: Re: Doc for multiple interfaces
Next by Thread: [no subject]


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads