RE: title caps and API documentation (was: English 101)

Subject: RE: title caps and API documentation (was: English 101)
From: "Susan W. Gallagher" <sgallagher5 -at- cox -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 23 May 2005 13:07:12 -0700


I think what everyone is wondering is why you think it looks weird, because
to a programmer or an experienced API writer, it looks perfectly normal and
correct. And it really doesn't matter whether you use up-style or down-style
headings with it.

I suppose if it really and truely makes you wince, you could apply some sort
of typographical convention to it -- as long as you employ that same
convention in the body paragraphs. But it hardly seems necessary.

Just wait until it starts to make sense to begin a sentence or a paragraph
with the name of that function and see what fun you'll have! ;-) I've had
occasion to begin several sentences with ".NET" recently and I cannot tell
you how much I enjoyed myself!!!
<evil grin>

-Sue Gallagher

> -----Original Message-----
> From: bounce-techwr-l-100838 -at- lists -dot- techwr-l -dot- com
> [mailto:bounce-techwr-l-100838 -at- lists -dot- techwr-l -dot- com]On Behalf Of Monica
> Cellio
>
>
> ... Sometimes, in programming
> guides (or discussions of examples), I have section headings that contain
> the names of functions that begin with lowercase letters. It is
> technically incorrect (and misleading) to capitalize them, so if
> I'm using
> headline style I might end up with something like "Using
> refreshData under
> High Latency", which looks weird...
>
>


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! http://www.webworks.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



Follow-Ups:

References:
title caps and API documentation (was: English 101): From: Monica Cellio

Previous by Author: RE: TOOLS: Seeking "speshul" ergonomic chair
Next by Author: Re: watch your language! (or don't)
Previous by Thread: Addenda RE: title caps and API documentation
Next by Thread: RE: title caps and API documentation (was: English 101)


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


Sponsored Ads