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.
On 4/15/1999 6:51 PM, pete swisher (PSwisher -at- QUARK -dot- COM) wrote:
>1) Use the terminology from the dominant platform.
>1a) Use generic terminology. For example, "Swing-out menu", and explain the
>term at the beginning.
>2) Use the screenshots from the dominant platform.
>3) Use both keyboard commands and indicate what platform they are from. For
>example "Press Alt (Windows) or option (Macintosh) to ....."
>4) Have additional text and screenshots for differences in the inferior
>platform.
>5) Again, have additional text and screenshots for the new items.
If you're going to adhere to the style of the "dominant platform," be
sure you know which one that is. I was working with a company with a
large Mac and Windows installed base, and people there insisted that
"most" of the customers were Windows-based, in direct conflict with their
actual marketing data and customer surveys. For a company with a long Mac
history such as, say Quark, I'd guess that "dominant" won't directly
correlate to the computer marketplace, although I may be wrong. Have
actual installed-base data before deciding.
I can help with a few other problems, though:
1) Keyboard commands are generally indicated in the program's user
interface, and therefore don't need to be documented in every step of the
manual/online help. An appendix with a Mac-keyboard-shortcut summary and
a Win-keyboard-shortcut summary will not only be useful but will probably
get copied and pasted up next to each of the customer's licensed
computers.
Only if the keyboard shortcut isn't obvious (as many shortcuts in
FrameMaker, for example) or if there is no graphical equivalent of the
command (again, as in FrameMaker) should you document shortcuts in the
main text, and then I'd say (Mac) and (Win) as in the example you gave.
2) Assuming the screens are identical, mix and match screenshots, trying
to keep a platform balance. Windows users will be offended if all screens
are Mac, and vice-versa, but you won't alienate any of your user base (or
perhaps all of them equally?) if you have a balance of screens.
3) Have a section up front describing the differences in the platforms,
and explaining the choices you made in terminology. My experience
indicates this section will be pretty short.
Hope this helps,
----->Mike
Mac, Windows, and now Linux, for that well-rounded career...
