title caps and API documentation (was: English 101)

[Monica Cellio <cellio -at- pobox -dot- com>]

The recent discussion about capitalizing titles reminded me of a
dilemma I face when writing API documentation.  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.  This consideration has driven me toward
sentence-style capitalization, and occasionally not even that if the
function name is the first or only word in the heading.  However, we are
in the process of adopting company-wide style standards and in all *other*
contexts headline style is what people prefer.

What to do?  We could say that API documentation is different, but we
are moving toward more re-use (e.g., of overview material) so that's hard
to implement.  We could adopt sentence style throughout to avoid the
problem.  Or we could keep to headline style except where incorrect and 
just live with the weirdness.  I'm curious about how others have solved 
this problem.

Monica


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

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.