December 2005/January 2006

Volume 46, Number 3

Solutions, Inc.

by Ron Arner

Some recent tips, how-to's, and advice from the Rocky Mountain Chapter Listserve:

Thread #1: Good example of SKD/API doc on the Web

I've suddenly been asked to document an SDK/API for a client, something I don't typically do. I've read the info from a recent summary on CIC SIG list about this, which was helpful. Unfortunately, the one example cited is not in my local library and I have to discuss this with my client tomorrow.

Can anyone point me to a good example or two on the Web? I did a couple of Google searches, but nothing struck me as great. I'll summarize and we an add the info to the existing summary.

Thanks much!!!

Try these two sites. I have had luck at both of them:

http://www.iturls.com/English/SoftwareEngineering/SE_11.asp
http://strategis.ic.gc.ca/epic/internet/ininfodev.nsf/en/h_00157e.html

I haven't kept up with the latest techniques for documenting programs. The last time I documented a function (routine, API, etc.) library was in 1999.

The classic program function documentation is the set of Unix man pages. I found sample man pages at http://bama.ua.edu/cgi-bin/man-cgi

My experience from 1984 through 1999 is that there are two levels at which you can document programs.

At the first and more superficial level, you can take comment information from the source file and reformat it. Depending on time and money constraints, that may be all you can do. If you have a bit more time and money, you can interview the developers and capture more information.

At the second and more comprehensive level, you review the comments in the source code and then you write the function documentation from scratch. That involves lengthy discussions with programmers and some basic knowledge about how the functions work.

In other words, function documentation is whatever you and the client want it to be. I've seen function documentation that writers produced in next to no time by having the developers strip out their comments from the source files and reformat them for input to Word or FrameMaker. Usually, that documentation is useless for learning. It simply provides a list of command syntax, options, values, returns, etc.

Occasionally, I see really good function documentation that people can actually use to learn how the functions work.

All the above is a long-winded way of saying that if I were talking with a prospect about documenting APIs, I would want to see the source code and any prior attempts at documentation, I would want to know a bit about the audience (senior programmers? highly skilled technicians?), and I would want to know about the prospect's goals. Do they just want a manual? Is it critical that the audience can use the function documentation? You might also ask what kind of training and support the client provides for the APIs. Training documentation can be a good source for example API calls, etc.

Program documentation can be fun (in a techie sort of way), but it's a different world from user guides!

Thread #2: Recommendations for antivirus?

Norton Antivirus, while reliable in preventing infections to my PC, seems to make it run a little slower each year.

Can anyone recommend a good replacement for Norton, one that doesn't bog down my PC? I've read several online reviews of various products, but I'd like to get some real-world feedback.

Thanks, and happy holidays!

AVG anti-virus is lightweight, and you can get it for free at free.grisoft.com. The subscription version is a little more robust.

I use Avast! 4 Home Edition, which works pretty well, as far as I can tell so far. It is free for home users. You can learn more about this product at www.avast.com.

Thread #3: Wacky Warning Labels

As a sort of belated follow-up to …'s post last week, here's the flip side of writing on technology...

http://www.wackywarnings.com/

This year's winner: "A heat gun and paint remover that produces temperatures of 1,000 degrees and warns users, 'Do not use this tool as a hair dryer.'"

It does not top my all-time favorite (click "Past Winners"): A smoke detector with this warning "Do not use the Silence Feature in emergency situations. It will not extinguish a fire."