Expert: Leslie - 6/13/2006

Question
I've just volunteered for the assignment to document half a dozen or so APIs (Java and C++), and I'm trying to get information on the best way to go about this type of writing and what tools are available.

I've seen some information on the web about the best tool for generating docs but what I haven't seen is information on the best way or the best tools to edit developers' comments within the code. From what I've seen of the developers' writing in our company, the text need to be heavily edited before they can be extracted into, say, Javadoc or Doxygen. Is there an easy way take the comments from the code, edit the text, and get it back into the code without actually having to touch the source files? Are there tools to do this?


I'd be very grateful for any advice.


Answer
Marissa,

I do not know of anyway to take the comments from the code and edit the text. What you say about the big need to edit the writing is true, and is at the heart of the tech writer's job.

Once long ago, some program writers wrote their code in Word Perfect. The handy part of Word Perfect was that the coding could be formatted differently than the documentation and thus was easier to prepare the program and documentation. With Java, you may be able to do the same thing with Office tools. With the C++ code, I am not sure.

Check the web for professional tech writer organizations. See what they may recommend for editing tools. Often these organizations have reviews of different tools that they share.

Wish I could be of more help.

Leslie