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.
A client of mine does not yet have a product API reference, so users rely heavily on
the explanatory information in the header files. Code comments are separate.
When there is an error in a company's software code, and (after a user
unsuccessfully tries to do something) a result code is returned because of this
error, is it ever okay to indicate in the header file this particular reason for the return
code? If so, how? The code of any software maker contains errors, of course.
This company has suggested that the header could be in the following format:
CannotGetXYZName, "BUG: Cannot get XYZ name"
By contrast, for errors returned when the user makes a mistake, the company
uses the following format -
ReadData, "Error reading data"
or
ReadData, "Cannot read data"
When the fault is with the company's code itself, what would you do, other than
the BUG: arrangement (except for occasionally addressing problems in the
ReadMe)?
Thank you.
Goldie
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
