Writing A Software Technical Reference Manual (part 2) - Improving Yourself (
Page 5 of 6 )
With the document done, you are ready for review. The review process of
any technical document has two aspects: the technical review and the
editorial review.
In the technical review, the intention is to verify that all the
information provided is correct. This is by no means a trivial job, and
the best way to go about it would be to provide a checklist to the
reviewer for each section. An example for the section on APIs would be:
1. Is the name of the API correct?
2. Are the access methods mentioned correct?
3. Are the boundary values all present and accounted for?
4. Are the arguments required all stated correctly?
5. Are the return values correct?
Such an enumeration not only ensures that the reviewer focuses on the
important points, it will also help him/her notice missing pieces of
information.
The editorial review can also follow the same process. The important
aspects to assess in an editorial review are:
1. Is the grammar and spelling correct?
2. Is style usage consistent?
3. Is verbiage used consistently?
4. Is the tone of the document consistent (active versus passive voice,
first person versus third person)?
5. Is the flow of the document logical?
6. Are the headings indicative?
7. Is any paragraph too long?
8. Does a particular section address more than one issue? Should it
really be split or sub-divided further?
9. Is there too much or too little information on any aspect?
10. Is any particular point in the main document body that would be more
suitable as an appendix?
11. Should any portion of the appendices be in the main document body?
Potential reviewers would be co-developers - ideally the people who
developed the requirements specification and the design document - as
well as other developers or managers who worked on the technical aspects
of the project. A wise practice would be to have more than one reviewer
for each item and start incorporating feedback only when all reviews are
in.
Another consideration in the delivery of the manual is the version
nomenclature. You could tie this in with the application's "xx.yy"
nomenclature, with "xx" changing with every baseline change, and "yy"
changing for every intermediate release of the manual. Also, when you
revise the document, do record a reason for, or description of, the
change.
