Home arrow Practices arrow Page 5 - Writing A Software Technical Reference Manual (part 2)

Improving Yourself - Practices

With the groundwork out of the way, this concluding partexamines the standard components of a technical reference manual,explaining what goes into each section and why. It also discusses theprocess by which such a manual should be reviewed and vetted prior todelivery to a customer.

  1. Writing A Software Technical Reference Manual (part 2)
  2. Starting Off Easy
  3. System Shock
  4. Remote Control
  5. Improving Yourself
  6. Sealed With A Kiss
By: Deepa L, (c) Melonfire
Rating: starstarstarstarstar / 3
February 13, 2003

print this article


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.

>>> More Practices Articles          >>> More By Deepa L, (c) Melonfire

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: