|
|
|
|
|
Consider one of the buzzwords of software development: code reusability. In order to employ existing code in other applications, the engineer has to know what the code does. More often than not, the engineer turns towards the header and source files to get all of the information they need directly from the code.
Based on where they obtain information and the requirement to comment their code, the software engineers are not very far away from more robust code extraction tools. What they may lack are:
A template for code comments.
Code comments having the proper format for an extraction tool.
Time and desire to mark-up and/or alter existing files.
This is where a diligent technical writer comes into play. The technical writer can:
Help define the minimum template for all code comments.
Insert templates into the code.
Convert any existing code comments into the new format and fix any language errors in the process.
If the technical writer cant figure something out, they can flag it for the software engineer, who ultimately still has the responsibility to comment the code.
Whereas technical writers may also have limited time and desire, such work is in more in line with their job description. A tool that extracts information from the source-code becomes self-serving for the technical writer.
The extraction tool working on the source code:
Exposes the deliverables of the software developer in an organized fashion.
Gives the technical writer 80% or more of the reference material for the API documentation.
Improves the accuracy of the documentation suite, because prototypes come directly from the code.
Improves communication between technical writing and engineering.
Shifts the effort of documenting and maintaining the API reference material to the owning engineering.
|
|
|
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02