Documenation review standards

Regrettably, I do not know of any reference documents of the nature you have described. One of the unfortunate aspects of the current state of the software development industry is that there are no set documentation standards that one can "borrow" when starting up a development project. The "document review process" is even less standardized and documented.

I have, in the past, established both databases and Word templates you use in developing documentation. I have experienced mixed success with each of these; however, the databse approach seems to have provided a clearer ability to review the current status of the documentation with regard to whether certain features have, at the very least, been documented to _some_ extent. However, in each case, unless someone reviews the actual documentation and compares it to both the "standards" and to the actual program/application/system being documented, one can never be extremely sure that the documentation is of any ultimate use.(As an aside, I once created a "documentation generator" program that spewed forth documentation according to the corporate "standard". This program accepted about 20 "application specific" words/phrases and then generated essentially nonsensical text which judiciciously included these words/phrases. The stuff read pretty well but, at the end of it, you had the feeling that it didn't really say anything. Interestingly enough, our documentation review process consistently passed these documents because they conformed to the "standards" and _seemed_ to be about the project.)

Regrettably, I do not know of any reference documents of the nature you have described. One of the unfortunate aspects of the current state of the software development industry is that there are no set documentation standards that one can "borrow" when starting up a development project. The "document review process" is even less standardized and documented.

I have, in the past, established both databases and Word templates you use in developing documentation. I have experienced mixed success with each of these; however, the databse approach seems to have provided a clearer ability to review the current status of the documentation with regard to whether certain features have, at the very least, been documented to _some_ extent. However, in each case, unless someone reviews the actual documentation and compares it to both the "standards" and to the actual program/application/system being documented, one can never be extremely sure that the documentation is of any ultimate use.(As an aside, I once created a "documentation generator" program that spewed forth documentation according to the corporate "standard". This program accepted about 20 "application specific" words/phrases and then generated essentially nonsensical text which judiciciously included these words/phrases. The stuff read pretty well but, at the end of it, you had the feeling that it didn't really say anything. Interestingly enough, our documentation review process consistently passed these documents because they conformed to the "standards" and _seemed_ to be about the project.)

The most basic QA process is a checklist, and that might be a good place to start. In monitoring development of testing scripts, for example, I've often come up with a template and a checklist. The template gives someone quidance and a format and expectations; I use the checklist to look for specifics and for the main characteristics or items that should be included in each section of the document. The checklist may grow as I discover what works and what does not.

Interesting article on checklists at http://www.stsc.hill.af.mil/crosstalk/1996/01/defining.asp/.

Also: http://www.ligo.org/lscprpguide.pdf

Both these basically take the desired standards, or requirements, and then develop categories of what to review in them with a few guiding questions under each. You should also define your process -- who will do it, how they will do it, how they will present their findings, how revisions will be handled. This could be a fairly simple outline or checklist (1-2 pages).

This one (http://obswww.unige.ch/Instruments/GIRAFFE/Files/VLTdoc/pdf/docReview_ins1.0.pdf) includes a flowchart of the process they used -- a visual like that can make it easier to walk through. Note that it also provides a format for the reviewer, which will guide what kind of things the review needs to look at and evaluate.

Hope these examples are useful. The principle of defining your 'requirement' and then testing that requirement apply easily here. Define an outline or template or existing standard to use, and then develop a checklist to mirror it, and describe the process (and roles) for how the review will be done.