Cross-platform documentation

Subject: Cross-platform documentation
From: pete swisher <PSwisher -at- QUARK -dot- COM>
Date: Thu, 15 Apr 1999 16:51:03 -0600

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.

Thanks,
Pete

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: There's more to it than money (Was: How Do You NOT Mention Salary First?)
Next by Author: User friendly term for Metadata
Previous by Thread: Resources for New Writer / Department
Next by Thread: Re: Cross-platform documentation


What this post helpful? Share it with friends and colleagues:


Sponsored Ads