How to document column names?

Subject: How to document column names?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 11 Jun 2004 14:41:43 -0400

Emily Allen wonders: <<I'm working on some on-line procedural documentation for a GUI and one of the columns that I need to reference has a name that does not at all represent what is displayed in that field. Any suggestions/standards as to how to document this?>>

First step is to try getting the developers to change the name to something users can understand. Why call it "cat" when it's a "dog"? Sure, you can teach the user that cats are really dogs, but why would you ever want to? Changing a column name is hardly rocket science, and no developer should put up too much of a fight. However:

<<I have chose to use the name that the GUI displays and then included a note informing the user what the column represents.>>

Realistically, you can't always talk developers into doing even obvious and simple changes. That being the case, document what the user will actually see.

<<Is this going to cause users anxiety when looking at the documentation? Am I going to be confusing them?>>

Of course, but it's not your fault. Try to fix it, and if you can't, do your best to make it clear that the developers are morons, not you <g>.

--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more!

From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.

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- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

How to document column names?: From: Allen, Emily

Previous by Author: Website development tools on Mac?
Next by Author: ADD/ADHD problems and tech writing/editing careers?
Previous by Thread: How to document column names?
Next by Thread: RE: How to document column names?

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

Sponsored Ads