Contents 
 Index 
 "TPT User's Guide" 
 < Previous 
 Next > 

Writing Quality in the API Documentation

The issue of writing quality in the API documentation may never be resolved, because the software engineers own the code. The trade-off for getting them to update their comments to reflect the code at the same time they are making changes to the code is probably worth any language errors that they might introduce and that don’t get fixed immediately.

If the software engineers know their writing (e.g., comments that get extracted into the API documentation) will be exposed to a wider audience:

1 They can willingly let the technical writer edit their comments.

2 They can let management dictate that the technical writer edit their comments.

3 The technical writer can leave it as the engineer wrote it.

With regards to number 3: let's look at the big picture. Is it really going to matter to the API documentation audience - other engineers - whether the engineer who wrote the comments had a typo, a run-on sentence, or other language blunders? Will the audience - other engineers - even see the error [maybe] or care [no, not if the other information is accurate]? The audience cares more about information than its delivery. They also recognize that they can’t throw stones at things that their own code might be guilty of.

Note: This is not meant to advocate releasing API documentation that is riddled with errors in the form of typos and grammar mistakes. It is meant to temper our inner control freak who might impose unrealistic expectations and processes on others in our effort to obtain grammar-error-free documentation nirvana. With compressed development cycles and frequent releases, there will always be next release to incrementally improve things more. When issues of wording ownership arise in source files, next release can often be a better time to divorce text from its author (the software engineer) with less resistance.



 "TPT User's Guide" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-hug-02