How to document column names?

[Geoff Hart <ghart -at- videotron -dot- ca>]

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! http://www.macromedia.com/go/techwrldemo