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

["Kathleen" <keamac -at- cox -dot- net>]

Hi Monica,

When odd names fit into a category, such as function names, you can
apply a distinctive style to them throughout the document, and provide
the style definition in your documentation. Then, when such names are
included in a title, it will be clear that the word is referring to a
function (or whatever).

'Course, it will still look odd (maybe odder than before), but it will
be clear that it was an intentional usage. For example, we used the
courier font when we referenced file and folder names (I think that's a
fairly typical strategy). I didn't particularly care for how it looked
along with the rest of the text, but I thought it was helpful to the
reader. I've also seen people use quotes for such situations, but I
don't think the point of that strategy is very clear to the reader.

Kathleen

-----Original Message-----
From: Monica Cellio
 
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.