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.
Do we help the user complete the immediate task or ultimate goal?; was, "RE: Use of 'populate'"
Subject:Do we help the user complete the immediate task or ultimate goal?; was, "RE: Use of 'populate'" From:"Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 6 Mar 2008 10:02:39 -0800
Brian's illustration raises the important distinction of whether one is
writing with the intent of helping the user to complete the immediate
task or the ultimate goal.
"Enter the date in the Approval Date field" puts the user in mind of the
immediate task, namely, filling in GUI or command line fields.
"Enter the approval date" puts the user in mind of the ultimate goal,
namely, getting the application to do something.
Whichever one chooses, it should remain consistent throughout the docs
(of course). I wonder which (if either) is better and why. Thoughts???
Leonard C. Porrello
SoleraTec LLC
www.soleratec.com
-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of Gilbert, Brian
Sent: Thursday, March 06, 2008 9:47 AM
To: Combs, Richard; Michelle Vina-Baltsas; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Use of 'populate'
Just a follow up to what others have said.
I would not use "populate" in your example for the reasons others have
provided.
If there is more than one way to get the data in a field (type, select
from a calendar, copy/paste, etc.), I would use "Enter." If you can only
get the data in the field by typing, then I might use "Type."
As for "Populate the Approval Date:," I would to use one of the
following:
Enter the approval date.
Enter the date in the Approval Date field. (Assumption:
Enter tomorrow's date as the approval date.
I generally like the first one, but it depends on the audience. I would
use the second if I need to let the user know about specifics such as
"Enter today's date in the Approval Date field" or if there are multiple
date fields that could confuse the user.
Also, unless there is another Actions item for the dialog box or window
or there are so many items that the user could get confused, I would use
"Click Actions" instead of Click the Actions button.
-----Original Message-----
From: techwr-l-bounces+bgilber=transunion -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+bgilber=transunion -dot- com -at- lists -dot- techwr-l -dot- com] On
Behalf Of Combs, Richard
Sent: Thursday, March 06, 2008 9:58 AM
To: Michelle Vina-Baltsas; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Use of 'populate'
Michelle Vina-Baltsas wrote:
> How do you all feel about using the word 'populate' in
> technical documents?
>
> For example,
>
> 1) Click the Actions button, then select Modify from the menu.
> 2) Populate the Approval Date:.
> 3) Populate the CR Number:.
I'll join the chorus of people declaring this use an abomination. But
once I got over the queasiness induced by "Populate," I noticed a couple
of other issues with your example.
Maybe Step 1 is just made up -- surely, you don't click a button to open
a menu, do you?
As for Steps 2 and 3, for crying out loud, lose the colons!! The field
name may be followed by a colon in the interface, but that doesn't mean
you should slavishly copy it into your document. A colon followed by a
period is a horrible, horrible thing -- fingernails on a chalkboard.
IMHO, of course.
Richard
------
Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as bgilber -at- transunion -dot- com -dot-
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as
Leonard -dot- Porrello -at- soleratec -dot- com -dot-
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
