Re: Title case in documentation

Subject: Re: Title case in documentation
From: Di <dicorrie -at- gmail -dot- com>
To: Keith Hood <klhra -at- yahoo -dot- com>
Date: Mon, 23 Apr 2012 10:20:04 +1200

With the UI, I show it as it is and I don't use quotes except on the
names of some check boxes in our release notes. Our release notes are
in a database with no body format ability. The quotes make it easier
to see the name of some of the more peculiarly named check boxes. In
our user documentation I mainly use quotes to show something you pick
from a list.

To use some of the more advanced capabilities of our software
successfully, you need to understand end to end processes that you
can't see on the UI. I give proper names to these processes even
though they are not visible on the UI, and so they get caps too.

If everything starts to look over-capitalised I review them to see if
I can get rid of any. Often its because a word that is on the ui or in
a process name has got capitalised throughout, by someone who needs
reminding of the old rule I think of as 'the Government is also a
government'. Or I have got over-attached to my new name for a new
process and am using it way too often.

Di

On Mon, Apr 23, 2012 at 4:19 AM, Keith Hood <klhra -at- yahoo -dot- com> wrote:
> 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.
>
> http://bit.ly/doc-to-help
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as klhra -at- yahoo -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> 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.
>
> http://bit.ly/doc-to-help
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as dicorrie -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> 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.

http://bit.ly/doc-to-help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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


References:
Title case in documentation: From: Kim Bieler
Re: Title case in documentation: From: Keith Hood

Previous by Author: Re: Word 2007/2010 Resources?
Next by Author: Re: Help with a term
Previous by Thread: Re: Title case in documentation
Next by Thread: TechWhirl: Technical Communications Recap for April 20, 2012


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

Sponsored Ads


Sponsored Ads