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've think I've got a bit of a bias against the "interface-independent"
documentation you've described. When I'm an end-user, I know I
prefer the documentation to be as straightforward and specific as
What about setting up a single document with conditional text?
I'm don't know what software you're using for documentation, but
I know that FrameMaker lets you set conditional text -- so you can
produce several different versions from the same source document.
Best of both worlds.
pstaples -at- airwire -dot- com
> Charles Fisher wrote:
> > We are already writing what we call "interface-independent" doc, in
> > we don't discuss interface specifics for commands. For example, instead
> > writing "Press F10" or "Select File|Save," we simply write "Save your
> > work." There is a separate doc that gives specific about how to SAVE in
> > each interface. What we need help with is how to show screen images
> > respect to these different interface flavors. Do we
> > Produce a separate doc for each style of screen?
> > Produce one doc that includes all styles of screens?
> > Pick one style of screen and produce doc using it, not showing
> Assuming your screens have _generally_ similar layouts, this might
> work. Frame does this - FrameMaker manuals show, I believe, the Mac UI
> in all publications.
> > Produce doc that does not have any screen images?
> Another possibility that I've used: assuming the various interfaces are
> generally similar, produce a "generic" UI illustration - essentially
> line-drawings showing basic controls, without depicting controls
> specific to a particular UI.
> In my case, these line drawings were simple, black-and-white, with only
> basic control outlines, menus and labelling.
> 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