7. Logging Documentation

The final step in the modeling process—​documentation—​is extremely important and can mean the difference between models that are useful for a week and models that are useful for years to come. Thorough, well-planned documentation is key to the user/analyst being able to effectively use what the modeler has spent many hours building. Sloppy or incomplete documentation, on the other hand, is like finishing up an otherwise well-built house with a bad paint job. It can serve to cover up all the good work the modeler has done and give the end user the false impression that bad documentation is an indicator of bad measurement, organization, development, and/or evaluation.

Fortunately, when included in the planning process, good documentation is easy to produce. Once again, the way one sets up and produces documentation is highly dependent upon the purpose of the model. There are several questions the modeler (who now takes on the role of technical writer) must address to assist the end user(s):

  • Who will be using the model?

  • What are the user(s) going to do with the model and why?

  • What information can I give about the model that might save the user some time or frustration?

Documentation can exist in several different forms. It can be a comprehensive chronological or topical summary of the project as a whole. It can be attribute tags (which are available in BRL-CAD 6.0 and later releases) about individual shapes and regions. Or it can be just some notes to help the user work with the model (e.g., to explain how to show articulation).

Regardless of the type of setup, the following recommendations are made to achieve effective model documentation:

  • Tell what it’s got and what it’s not: It is useful to record not only what components have been included in the model but also what components/details have not been included (and why). This will remove doubt as to what the end user does and does not have.

  • Tell the purpose of the model: Although the primary end user may know exactly what the intended application of the model may be, the documenter should consider the possibility of other users becoming involved during a model’s lifetime. Furthermore, these users may not know the model’s original purpose and may try to use the model in a way in which it was not intended. The documentation should explain the choices the modeler made as well as identify, if applicable, ways in which the model has been designed for articulation and/or animation.

  • Tell when it was built: This information identifies the time period during which the model was built. This information can be especially important when modeling developmental items with continuously changing design or model specifications. If a model undergoes a radical redesign during any stage of the development process, the period of performance can help identify why the model does or does not reflect given redesigned components as well as identify when changes were implemented.

  • Tell from what sources it was built: It is important to note the type of data sources from which the model dimensions were collected (i.e., field measurements, special tools, mechanical drawings, or converted geometry). If a modeler physically measures an object, it is also important to note any specific manufacturing information (e.g., make and model, year of production, factory, etc.), any special designators or insignias, and any damaged or missing items.

  • Tell how it was built: This information records the significant techniques and configurations that were used to build the given geometry as well as any irregular or specialized constructions (e.g., for articulation, an intended ballistic impact scenario, etc.). Also included here are basic tree structures and any naming conventions used.

  • Tell the level of detail to which it was built: This information documents the specific tolerances and level of accuracy used to construct the model, as well as ways in which accuracy was checked (e.g., rtcheck and rtweight).

Documentation is often written at the end of the modeling project and published as a formal technical or summary report. Another good method is to document significant items as they are encountered throughout the modeling process. This practice records important information while it is fresh in the mind of the modeler as well as reduces the amount of writing required at the end of the project (when energy and/or interest levels may be low).

Finally, it is a good idea to embed the documentation (e.g., as a text file) directly into the database so that it always remains connected to the geometry it addresses. For example, the command

dbbinary -i u c documentation /home/fred/doc.txt

will create a BRL-CAD binary object named documentation, and the object will contain the text from the file named /home/fred/doc.txt .