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.
My rule is that the document reproduces *exactly* the spelling and case of whatever is shown on the UI. Even if what is on the UI is misspelled - in that case the misspelling is reproduced in the document. If both are misspelled, it's easier to be sure the user will recognize the correct screen feature. And if proves that yes, you really have looked at the actual interface.
I show feature names in bold text, and use quotes to enclose selections that are reached through features. So the document would read like this: Open the Somethingmenu and select "Next Thing."
Another thing I do is include qualifiers that identify exactly the nature of the thing. If "Custom Audit" is a button, I include the word "button." If "Acquire Memory Image" is a dialog box, I include the phrase "dialog box." If it's a title for a function, then I include the word "function" or "functionality" or something like that, to ensure the reader knows that title does not refer to a visible part of the UI.
Dunno if this is elegant but it works for me.
________________________________
From: Kim Bieler <kimbieler -at- gmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Sent: Friday, April 20, 2012 9:04 AM
Subject: Title case in documentation
First, thanks to all the excellent responses to my question about
screening tech writers. They were extremely helpful, in particular the
writing/editing exercise ideas.
New question: What is the best way to handle the names of features in
software documentation?
e.g., "Custom Audit offers the option to Acquire Memory Image, which
allows you to later perform acquisition of process and driver memory."
My personal preference is not to use title case for the names of
features (e.g., "Acquire Memory Image"), because it tends to make
English documentation look choppy and Germanic. However, I heard a
somewhat persuasive argument recently that it helps users understand
when they're seeing something that's named in the UI without resorting
to quote marks.
I would also prefer to use sentence case in the UI for page titles and
button and form labels, but not if we're going to use sentence case in
the help docs.
Obviously, the important thing is to pick one style and be consistent.
Just wondering if there's any usability implications to picking one
over the other. Have you seen any elegant examples of how to address
this issue?
Thanks,
Kim Bieler
www.kimbieler.com
@feadog
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
