The devil in the detail

When writing a quality system manual there is (at least should be) a need to talk about real-world objects. Let’s call them primary objects for lack of a better word. Examples are a product or a (software) bug (whether a bug is an “object” is of course also debatable but in the abstract world of software it is). Sometimes we on the other hand need to refer to some kind of representation of that primary object like a ticket in a bug tracking system (representing a real-world bug). Let’s call these objects meta-objects as they contain information about primary objects. Sometimes this causes no problems like when we have a product and a product specification describing the product. (The product specification is of course also a real-world object but it is not “primary” in the sense that it doesn’t have any justification without the primary object it describes.) In this case the objects have different names (“product” and “product specification”) and will not be confused.

Sometimes it is very convenient to use the same name for the primary object and its meta-object though. When for instance modeling a system in a UML tool, the modeler may describe real-world, primary use cases with meta-objects of the type use case in the tool. When we refer to “use case” in the quality system manual for such an organization, we don’t know whether we refer to the primary use case or its representation in the tool, the meta-use case. Many times this ambiguity goes unnoticed. The text may apply reasonably well to both objects. Sometimes we are able to infer from the text to which object it refers. But sometimes we may have a slightly larger ambiguity. Let’s say that we are developing a medical device and wish to manage the clinical risks potentially caused by the device. Let’s also assume that we have a tool for documenting and tracking individual clinical risks. When we in the quality system manual write “find all clinical risks” we can’t be sure if we are referring to the clinical risks already documented as records in the tool or if we are referring to previously unknown primary clinical risks. The editor of the quality system manual will also invariable go astray from time to time and describe the primary object when a description of the meta-object was called for, and sometimes vice versa. A primary use case is after all a rather different animal than the meta-use case in the tool.

It might be a little clunky to come up with different names for the primary objects and the meta-objects. What would we for instance call the use case meta-objects? “Meta-use case” doesn’t roll so easily off the tongue. I have therefore adapted a convention according to which all primary objects are denoted with all lower-case letters and the meta-objects with capitalized names.

This may not be a Nobel winning insight but I’ve seen confusion about this many times, and I have been confused myself, so I still wanted to share it.

Leave a Reply

Your email address will not be published. Required fields are marked *