Re: API Documentation

Subject: Re: API Documentation
From: puff -at- guild -dot- net
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 31 Oct 100 18:10:42 -0500 (EST)

Walden Miller writes:

> When to spell out numbers is probably the least of your problems if
> you are reading code. Make a rule and stick to it. here are the
> three rules I use:

I agree, with the caveat that this is one of those classic cases
where you can screw it up by trying to make it too "english-friendly".

> 1. all numbers when used with units in numeric format (e.g., 16 bit, 56K
> baud, 3 bits)

Absopositively. For god's sake, don't change technical numbers
to words just to satisfy some outdated newspaper writing style.

> 2. all integers above nine and below 1 are always in numeric format;
> otherwise spell them out.

My chief recommendation here (as somebody who's worked both sides
of the street) is to be aware of why the number is there and make
sure, when the specific numeric value is important (i.e. most often
when it must be used as an argument or as a limit or range for an
argument or parameter) that you make the numerical value clear and
emphasized, and easy to spot.

Often the user ends up scanning through the docs trying to find
the numeric value to make sure they're using a correct value. That's
the sort of thing that causes me to curse ill-informed writers who
think they're making my life easy by changing "8" to "eight".

> 3. all fractions are put into decimal format (e.g., not 3/4 but 0.75)

I lean towards decimal format as well, but again, be cognizant of
when the actual fraction is important, as opposed to when a decimal
version of the number will do.

> it really doesn't make any difference, but a rule takes the
> indecision away so you can concentrate on other things that are
> important in API docs.

True, but again, focus on understanding why the number is there
and how the reader will use it. "A _foolish_ consistency is the
hobgoblin of little minds." (Winston Churchill).

Steven J. OWens
puff -at- guild -dot- net

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Your web site localized into 32 languages? Maybe not now, but sooner than
you think. Download ForeignExchange's FREE paper, "3 steps to successful
translation management" at http://www.fxtrans.com/3steps.html?tw.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -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
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: Re: passive vs. active...usage...
Next by Author: Re: Appalling English
Previous by Thread: RE: API Documentation
Next by Thread: Diffing Docs


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


Sponsored Ads