Mac vs. Windows keys/buttons/etc. in two-platform documentation?

[Geoff Hart <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Missed the original question, but if I've parsed the discussion correctly,
the question was how to produce documentation for one product on two
platforms when the keystrokes, dialog box buttons, or menu names differ
between the platforms.

From _the user standpoint_, the best solution is to produce a customized
documentation set for each platform; that way, the user never needs to read
and ignore the details for the other platform and never notices that you've
tried to produce a patchwork, "one size fits all" solution. If you're using
something as sophisticated as Frame, you can use conditional text to set up
different versions for each platform fairly easily. And if you've got a
large number of customers, the additional cost of producing separate docs
isn't all that great, apart from a small up-front investment in designing
the conditional text. (The cost _could_ be prohibitive, though, for small
audiences, since the economies of printing require large print runs to
justify customization.) If you're only talking about online docs, then the
print run is irrelevant, and it's hard to justify not producing custom docs,
since the only cost is your setup time. And even if you can't use
conditional text, you can spend a little time with search and replace to
create a second version; all you need is a style sheet that says "OK on the
Mac = Damn straight! on Windows" and so on.

On the assumption that you have neither time nor resources to do the job
right, then there are a variety of compromises you can make that work
reasonably well.

1. Blackmail or threaten your developers until they agree to be consistent
between platforms. Button names like OK are established by default in many
programming APIs, but they're almost never carved in silicon; thus, it's
easy to change the defaults so that they are compatible between platforms.
(In fact, that's generally a good idea. In _every_ case, a button should
directly answer the question posed by the dialog box, and the default button
may not directly answer that question; "yes" or "proceed" is often better
than "OK" in response to a "would you like to...?" question.) Trying to
solve such problems through documentation is the wrong approach; the problem
is the interface.

2. Put both commands together, directly in the text. For example, the
Photoshop manual uses phrases like "Hold down the Option key (Mac) or Alt
key (Windows) and click..." I find this minimally intrusive and (being
platform-bilingual) helpful when I have to switch platforms.

3. Create a layout that gives you an inch or so of white space in the
margin. Use this space to display alternatives or shortcuts for various
commands, then focus the main text on the things that are consistent between
platforms. For example, the text might read: "Open the File menu and select
Save." for both platforms, even if the keyboard shortcuts differ. In the
margin, the shortcut text would read: "Control-S for Windows, Command-S for
the Mac". This could become cluttered for dense procedures, or it could work
very well indeed (I've seen it done this way before)... you'd have to
experiment with designs and your specific procedures.

--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca 
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens