Re: title caps and API documentation

Subject: Re: title caps and API documentation
From: Jeffrey Osier-Mixon <jefro -at- jefro -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 23 May 2005 12:07:06 -0700



might end up with something like "Using refreshData under High Latency", which looks weird.

As a sometimes-programmer, this doesn't look weird to me at all. It would look REALLY WEIRD if the heading was capitalized according to the demands of the Chicago style manual, which was written to address academic needs rather than computer API documentation.
Would you change the capitalization of a French or German word to meet English usage standards? If not, then I would suggest not doing it with computer languages, either. They are not in English, even though they appear to have English root stock.

It also helps to know the usage model for the document. This is API documentation, but API manuals are used in different ways. The heading above could only come from a usage manual, say The Blahblah API User's Guide. For reference material, every engineer I have talked to (including myself... yes, I talk to myself) vastly prefers functions to be presented in a framework structured according to the interface itself, with individual functions presented in alpha order. This makes functions very easy to find in the TOC without resorting to an index. In other words, if you end up with a TOC that looks like this:

4.2 BlahblahMaker
4.2.1 forgetData
4.2.2 readData
4.2.3 refreshData
4.2.4 sendData
4.2.5 writeData

then you are on the right track. (In my opinion, naturally.)

Jeff


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

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:
title caps and API documentation (was: English 101): From: Monica Cellio

Previous by Author: Re: Tech Writers as Hourly Employees?!
Next by Author: Re: Help vision?
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