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.
> Editing a manual that says, in part, "To open a new <thing>, click
> <b>Open... </b>. The UI element is Open... in the software. I changed it to
> Open (without the three ...) because I thought having three bold periods,
> then a single unbolded period, looked really dumb.
> Got my redlines back. Nope. Manual has to match the software. If it says
> Open... in the UI, it has to say Open... in the manual. The ... means that
> there is another window that displays on the screen and, also, if it was
> translated - have zero experience with translation - the UI and the manual
> have to match, or something along those lines.
> How does Open... help the user complete their task?
It doesn't. Instead, it reduces the readability of the manual and thus hinders the user. This is unthinking literalism, and it ought to be resisted.
Do any of the application's menu items display shortcut keys? If not, show them some examples and ask if "match the software" means you'd have to say "click <b>Open... Ctrl+O</b>."
Are there field labels ending with colons? I shudder to think that they'll make you write things like "the <b>Session timeout (minutes):</b> setting."
I suggest showing them examples of manuals or online help from respected companies that use the ellipsis convention in the user interface, but omit the ellipses in the documentation. That's just about everybody, I believe. "Look, Adobe doesn't do that, Microsoft doesn't, Borland doesn't, ..."
I guess how hard you should push or what you should do next if necessary depends on the situation: Are you a contractor or employee, who told you to do it the stupid way, what relationship do they bear to your immediate supervisor, etc.
Richard G. Combs
Senior Technical Writer
richardDOTcombs AT polycomDOTcom
rgcombs AT gmailDOTcom
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days. http://www.doctohelp.com
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-