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.
Like most companies, mine is now requiring documents that cover multiple
platforms. As a result, us writers are working on some new style sheets and
templates that specifically serve cross-platform documents. It has not been
very easy and I am wondering if anyone else on the list has some good ideas
about this. However, first I'll offer the problems and potential solutions
we recently identified.
Problems:
1) Interface elements. For example, "Shortcut" vs "Pop-up list."
2) Screenshots. Which platform to use?
3) Keyboard commands.
4) Other GUI differences. How do we explain standard differences between
Mac and Windows GUIs?
5) Platform specific differences. What if something exists in one platform,
but not in the other?
Potential solutions:
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.
This is just a first stab at it. I would appreciate some good ideas
(besides don't do it!) on how to successfully write cross-platform
documentation.
