TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Editing files that were generated from Javadocs once?
Subject:Editing files that were generated from Javadocs once? From:Geoff Hart <ghart -at- videotron -dot- ca> To:TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Nurit Zur <nurit286 -at- yahoo -dot- com> Date:Wed, 23 Aug 2006 09:08:40 -0400
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)