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 ofany technical document has two aspects: the technical review and theeditorial review.
In the technical review, the intention is to verify that all theinformation provided is correct. This is by no means a trivial job, andthe best way to go about it would be to provide a checklist to thereviewer 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 theimportant points, it will also help him/her notice missing pieces ofinformation.
The editorial review can also follow the same process. The importantaspects 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 itreally 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 moresuitable 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 whodeveloped the requirements specification and the design document - aswell as other developers or managers who worked on the technical aspectsof the project. A wise practice would be to have more than one reviewerfor each item and start incorporating feedback only when all reviews arein.
Another consideration in the delivery of the manual is the versionnomenclature. 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 yourevise the document, do record a reason for, or description of, thechange.
Next: Sealed With A Kiss >>
More Practices Articles
More By Deepa L, (c) Melonfire
