RE: Username or user name (generalized)

Subject: RE: Username or user name (generalized)
From: Steven Jong <SteveFJong -at- comcast -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 4 Apr 2005 20:57:34 -0400

I recently posted to ask for opinions on whether to match the capitalization of the UI in the documentation. (Collectively, you said yes.) This discussion of "username" versus "user name," and Taryn's well-known advice (hi, Taryn!) to follow the UI, leads me to dip another toe into the water.

Not only has my group decided not to follow the generally accepted practice of matching the capitalization of labels in the UI, we are not following the spelling or usage, either. For example, we have determined among ourselves that the correct term is "user name," and we use it consistently in the documentation (which I think is right and proper); at the same time, when we refer to the label in the UI that says "Username," we say to enter the user name in the User Name field (sic). Another example: The button says "UPDATE;" our documentation says to click Update. One more: The field says "Timeout interval;" our documentation says to enter a value in the Time-out Interval field.

The rationale for this decision is that we are not obliged to follow the peculiarities, or parrot the mistakes, of the UI, and that our users will have no trouble making the connection between what we call a thing and what the UI shows. I acknowledge that our engineers are as inconsistent as anyone's, and that our users won't take long to catch on to--and might not even notice!--these subtle differences. I don't prefer the vagaries and errors of the UI labels. At the same time, I believe that not following the UI, even when it's wrong, is against the practice of every software company I know of or whose output I've seen (and I've seen a lot!). Further, my experience is that not following the UI, even when it's inconsistent, is a tech writer 101 mistake that most writers and editors would "correct" without a second thought.

I made these points in my group, and I was outvoted. So I've changed the case and usage of the references to the UI in many places in my 500-page document. (I'm genuinely curious as to how far the policy goes: Should I refer to the User ID field as the User Name field too?) But just as a sanity check, I ask you: am I now an old fogey, out of step with current practice? Is it better to maintain consistent terminology and usage, boldly declaring our independence from inconsistent developers? Or is it better to slavishly follow them, even when they're wrong?


Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: What do you want from help? (was: Do online helps have chapter numbers)
Next by Author: RoboHelp For Word Crash/Reboot Problem
Previous by Thread: Re: Conference Handouts
Next by Thread: Re: Username or user name (generalized)

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

Sponsored Ads