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

Subject: RE: title caps and API documentation (was: English 101)
From: "Fred Ridder" <docudoc -at- hotmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 23 May 2005 16:29:26 -0400


Before you commit to the approach of applying special typography to
function names (and other special terms) when the appear in your
document headings, I'd suggest testing to make sure that you're
happy with what happens in your TOC (and cross-references and
maybe even index) as a result. Different tools handle this situation
differently, and you may find some unintended (and undesirable)
results. For example, I don't like the effect that character formatting
in headings has on the TOC in FrameMaker, so we don't use that
approach in our group's docs.

My opinions only; I don't speak for Intel
Fred Ridder
Intel
Parsippany, NJ

From: Monica Cellio <cellio -at- pobox -dot- com>
Subject: RE: title caps and API documentation (was: English 101)
Date: Mon, 23 May 2005 16:18:52 -0400 (EDT)


Thanks everyone for the input. It hadn't occurred to me to use the
same typographic conventions that I use in running text in the headings
as well; that seems like an easy way to address the issue.

Just to clarify "looking weird", what looks weird to me is seeing a
function name of this sort amid capitalized words that may be "less
important". The lowercase method name itself doesn't look weird to me;
I was a programmer for too long to think that's anything but completely
natural. (I would never, ever, capitalize the name, which is effectively
renaming it in the documentation.)

> 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! ;-)

Been there; done that. :-) I can usually write around the problem without
the text sounded stilted. I don't know what I'd do in a .NET world.

Monica

_________________________________________________________________
Don?t just search. Find. Check out the new MSN Search! http://search.msn.click-url.com/go/onm00200636ave/direct/01/


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

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.



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

Previous by Author: Re: Tech Writers as Hourly Employees?!
Next by Author: RE: LONG - A colloquial writing style?
Previous by Thread: RE: title caps and API documentation (was: English 101)
Next by Thread: Re: title caps and API documentation (was: English 101)


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


Sponsored Ads