TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
>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
>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
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