Editing files that were generated from Javadocs once?

[Geoff Hart <ghart -at- videotron -dot- ca>]

Nurit Zur wondered: <<We use Javadocs to generate API reference  
guides. However, we do not have access to the code and the developers  
do not always copy the updated text to the source code (almost never  
would be more accurate). Therefore, next editing round we have to  
edit again what we have already edited.>>

Even programming managers will probably understand that doing exactly  
the same thing every 6 months is inefficient and error-prone. The  
obvious solution is to make it part of the programmer's  
responsibility to update the code and to hold them accountable for  
doing the job right. Of course, "accountability" and "responsibility"  
are words that seem to have gone out of fashion in North America  
(can't speak for the rest of the world), and programming managers  
aren't always as clueful as one might wish. That being the case:

<<Is there a tool or method that enables to "single source" the  
comments that are used to generate the API reference guide? Either a  
tool that copies all the text back to the original files or a method  
of working that enables to use or copy the same text to both the  
source files and the documentation files.>>

I can't speak to JavaDoc, but I do recall that it seemed quite easy  
to do in Borland's Delphi programming environment. I can't tell you  
the details from the programmer's perspective because I only worked  
with the text, not with the code, but here's the gist of it:  
Essentially, the interface labels (e.g., menu and field names),  
dialog box text, error messages, etc. could be stored in an external  
resource/reference file. Instead of typing this text directly into  
the code, the programmers imported it by reference during compiling  
of the software. Your programmers should be able to tell you how they  
could do the same thing; it should either be supported directly by  
their programming environment, or trivially easy to program.

At my former employer, the developers shipped me a text-format  
version of the file, and I either printed it and annotated it  
manually with red pen, or edited in Word using revision tracking so  
they could approve each change. (Different programmers, different  
preferences.) So long as you save the file in .doc format to enable  
revision tracking, and in "text" format when the editing is complete  
so it can be reimported into the programming environment, editing in  
Word works well. Never had a single problem.

There are two big gotchas in this approach: First, you are seeing the  
text out of context (i.e., not surrounded by the actual program  
code), so you have to review ("proofread") the interface after  
compilation to ensure that the labels are correct. (Alternatively,  
you call up the programmer and ask "What function is the word  
'tanstaafl' associated with?") You can also walk through the  
interface one feature at a time, then search the text file to find  
and correct each chunk of text. Second, you have to be scupulously  
careful not to screw up any of the punctuation or formatting; most  
software uses odd syntax, such as '' or & before special characters,  
that must not be damaged.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart   ghart -at- videotron -dot- ca

(try geoffhart -at- mac -dot- com if you don't get a reply)

www.geoff-hart.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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

WebWorks ePublisher Pro for Word features support for every major Help 
format plus PDF, HTML and more. Flexible, precise, and efficient content 
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -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.