John E. Darrow -- FAQ about the Documenting Java and C++ API courses

John E. Darrow [ resumé | main page ]

Frequently Asked Questions ...about the Documenting Java and C++ API courses

There are a few of us who really want to take your course but there aren't enough to "fill a class" and justify the expense. Any suggestions?

Sometimes neighboring companies are willing to pool their writers for a class, with one of the companies "hosting" (that is, providing the room--all that is needed is an overhead projector and enough space for people to take notes).

Your local university or university extension may be willing to host the event.

If noone is willing to host but enough writers are willing to sign up, we could certainly arrange for a conference room somewhere in your area, though the fee might be increased slightly to cover the expense.

Present the issue to your manager. Your manager may have resources of which you are not yet aware.

What does it mean to "document the command line syntax" of a program?

It means to explain how to start a program from a command line (for example, a DOS or UNIX prompt).

The programmer may have built in extra options and variations that the writer must present to the reader. Certain symbols can be used in the documentation to help the programming reader quickly grasp these options and variations. Here is an example of the MyProgram program and its command:

java MyProgram <filename> [ -start <sourcefile> ]  <number> ...
The angled and square brackets and the ellipsis can be used to communicate a wealth of information to the reader who understands such symbols.

What does it mean to "document an applet"?

This is applies to the Java course only. For the most part, an applet is a Java program that requires a web browser to run. Applications are Java programs that do not require a web browser.  Loosely speaking, to document an applet is to explain to the reader how to use the HTML tag named <APPLET> for the particular applet the writer's company is selling.

What does it mean to "document the API" of a program?

"API" stands for "application programming interface". Some, but not all, programs provide a way for other software to interact with your company's software at the programming level. Specific programming expressions are created by your company's programmers for such interaction and it is your job to document those expressions for a programming reading audience. To "document the API" of a program is to provide whatever information the reader needs to be able to write software that interacts with your company's software.

A simple example that many can relate to is Netscape's browser and other companies' plug-ins. Have you ever been using a web browser and then it loads a plug-in or asks you do download a plug-in? Many of these plug-ins are written by companies to work with Netscape's browser software. If you worked as a tech writer for Netscape, you might need to explain how other companies can create plug-ins so that they work with the Netscape browser, even appear to be part of it. You would be explaining the API of the underlying browser software.

At bare minimum, you must identify the functions or methods that the programming customer would use. For each, you must identify its name and purpose, provide a description of the information it needs to get its job done (its arguments or parameters), and describe any information it gives back when it has done its job (known as its return type). Much of this information you can get directly from the code, once you know what patterns to look for, as taught in this course. The rest you must get from your programmer (keep that portable tape recorder handy!).

Much more is taught in class about documenting an API.

Does a writer need to know Java or C++ if not writing API documentation?

I spend a good portion of the course on object-oriented thinking, mixed with what it turns into in C++ or Java. Anyone (including non-tech writers) who wants to be solid in those terms we hear tossed around (class versus instance/object, encapsulation, overloading, interface, functions, methods, arguments, variables...) would benefit greatly from from this course.  Past students have reported they now have a clue what programmers are saying to each other in meetings and in some cases have been able to contribute ideas.

Though the writer's job might not include API documentation and thus require no knowledge of code or coding practices, the writer may benefit tremendously from learning such concepts. In my experience, relations with programmers are better when they recognize I know what I'm talking about.

Why is grading based on a final?

Some companies require me to provide grades, some don't. I often pass out the final anyway, just so that students can get a sense of whether they have learned the key topics.

The final tells me and the student what the student has learned. It focusses on those things that I think the student must know when leaving this course.

Some managers attend my courses and want to know what questions are good for an interview. My answer: those on the final. So, if you are seeking an API writing job, you should be ready to answer questions like those on the final.

I strive to do my part to help each student get an A on the final: I use in-class exercises, allow for any level of question, repeat the important concepts often, and allude to what will be on the final.  The final is open book and, to some extent, open teacher. In one student's words, "I don't see how anyone could not get an A."

What is different in one course from the other?

Both courses build upon a similar presentation of object- oriented thinking. And Java shares various code characteristics of C++. However, there are many significant differences in appearance of each language's code, differences worth studying closely and separately from the other language.

I encourage students of one course to attend all hours of the other course. Most students who have taken both courses have noted that the repeat of such material was very helpful in solidifying their understanding of many of the core concepts.

Do you offer either course as a one day seminar?

Yes. The key differences from a normal course are these: (1) elimination of most exercises, (2) deferring of questions until the end of the seminar and (3) a faster pace. (Many of my past students could have taken in the material at a far faster pace. I have typically taken it slow in class to answer the questions of the slower students.)

Would you be willing to combine the Java and C++ courses into one longer course for us?

Yes. I could cover both in three days.

Have you written a book on this topic yet?

See the description of the book.