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.
MDoyle TStorer wrote:
> The company where I work as an editor is producing an application developed
> using the Eclipse development environment. The interface real estate of the
> application largely mimics that of the Eclipse workbench. The writers (and
> I) are wondering how to refer to the interface elements. I've been looking
> at the Eclipse User Interface Guidelines available at:
>http://wiki.eclipse.org/User_Interface_Guidelines,
> but these are mainly for the Eclipse workbench itself. I would be interested
> to hear how other technical writers are approaching Eclipse-designed
> applications.
You need to put this query to your app developers, to find out why the
app is so much like Eclipse and who they think the target audience is.
Then I think you will want to put your questions to the target audience
and see if they are comfortable with the Eclipse model and terminology.
I haven't documented anything developed with Eclipse, but considering
your question in more generic terms, and knowing only what you've said
about the app, this sounds to me like the app is built on an unfamiliar
model, and the target audience (and your documentation team) is going to
have to _learn_ the interface, as opposed to grasping it intuitively.
They'll learn it and grow into it, but they may need a training session
to supplement the documentation your team produces.
I think your quest for a more intuitive approach to the UI is
commendable, but a fool's errand if you don't characterize the audience
before you start targeting their intuitive powers. "Intuition" about a
UI comes with getting acquainted with the design of the app, which a
training could provide, in the form of overviews of the model and
hands-on (computer lab) practice. You won't be dumping a tangled mess of
non-intuitive quasi-Eclipse terminology on them. Rather, you'll be
unfolding an intricate design before their very eyes, pointing out along
the way how the design lets the app do what they need it to do, how they
will use it to meet their goals. You'll spin it for them, and they'll
see the light, in whatever terms you give them.
Whether to give them the straight Eclipse-based terminology, or to
doctor it to have more friendly terminology, is a question you could
involve the audience in. If they're technically energized and able to
grok object-oriented concepts like containers, then I would lean toward
giving them the unvarnished object terminology of Eclipse, reasoning
that they would then be more conversant and more on the same page with
the designers and developers of the app, which would enhance their
intuition, if you see what I mean. I mean that if I put myself in the
audience's shoes, I think the intuition comes with understanding the
design of the app, and that would be more valuable to me than the
limited power I'd get by learning the glossy version of the app in terms
of an overlay of friendly UI terms.
Still, I see your point about overlaying the technology with a
user-friendly skin of terminolgy etc. Most widespread major apps do
exactly that. For examnple, MSWord manuals and online help don't
describe or explain Word in terms of the fractally complex object model
underlying the app itself. You can get help on the object model in Word,
but knowledge of it isn't required to use the app and accomplish basic
goals. So you've got a whole lot of well-known Windows terminology you
could adapt to your Eclispe-based app, provided that your app is
designed as a standard Windows app.
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
