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.
Subject:Re: To case or not to Case From:"Jeanne A. E. DeVoto" <jaed -at- jaedworks -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 20 Jun 2000 04:03:53 -0700
At 3:26 AM -0700 6/20/2000, Carnall, Jane wrote:
><disarmname> <fullghostname>
><disarmname> <FullGhostName> / <ArmedGhostName>
>[...]
>My instinct always tends towards making things consistent. In this case,
>however, I wondered if it was worthwhile leaving the commands inconsistent
>and pointing out that they are case insensitive.
I'd make them consistent in the documentation, for this reason:
Documentation should model good coding practice, and that means that
(almost without exception) code fragments in the documentation ought to be
written in the preferred form, if there is one (as there is in this case).
Even if there is no preferred form, consistency is a virtue when it comes
to example code, and writing everything in lowercase avoids any confusion
along the lines of "Is 'fullghostname' a different token than
'FullGhostName'? If it isn't, then why does it appear two different ways?"
You should explain somewhere that they're case-insensitive, of course, but
getting used to writing everything lowercase isn't going to do your readers
any harm or prevent them from learning any functionality, and it will have
the advantage of teaching them the preferred format.
