Re: To case or not to Case

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.

--
jeanne a. e. devoto ~ jaed -at- jaedworks -dot- com
http://www.jaedworks.com






Previous by Author: Re: Tech Writer screening questions)
Next by Author: Re: Linux
Previous by Thread: To case or not to Case
Next by Thread: RE: To case or not to Case


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


Sponsored Ads