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: 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).
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.