Visualize | Handbook
Cruft Buster creates handbooks, documentation that follows the primary focus and incorporates other views. In the case of a public utility that delivers water from reservoirs in the mountains to the taps of people in the city, there likely are many different types of handbooks. One handbook might include troubleshooting procedures. It might include maps of the underground pipes. This handbook would be optimized for a particular "domain", the domain of water flow. Another handbook would be centered around staff and the needs of the staff to administer and maintain the system that transports water, and might include an organizational chart of staff hierarchy. It isn't helpful for somebody who is referring to a handbook containing maintenance procedures for a water pump to have to wade through HIPAA regulations, but it would be appropriate for a staff handbook.
Consider a car, another complex system. Many people see the need to be able to work on their own car without needing to pay a mechanic. Like any system, a handbook for the system can help accomplish this. There is a book titled How to Keep your Volkswagen Alive: A Manual of Step by Step Procedures for the Complete Idiot written by John Muir. The target audience for the book is people that own and wish to repair Volkswagens with air-cooled engines made from 1949-1978. One of the things that makes the book more useful than competing books is the distilling of information into readable diagrams that are hand-illustrated. This is more useful than a photograph. It illustrates a key difference between discovering knowledge via automated discovery and gathering knowledge with a limited schema in mind.
Handbooks can include many different kinds of models; however, they take on the structure of the primary domain. This is illustrated by the ceremony of the Christmas tree. When you cut down a Christmas tree or select a tree at a lot, you choose a tree with a certain general shape, character of needles, depth of the branches, and height. This affects the overall look of the tree when you have finished decorating it. There are different types of decorations. In your household, let's say, colored strings of lights are placed on the tree first. Tucked away on the top shelf of your closet, is a batch of silver globes you got from a thrift store when you first moved in together with your partner as lovers. Every year those go up first, with great care and ceremony, perched between the branches and the strings of lights. After your second child was born, you started stringing popcorn. It was a fun activity that everybody could participate in, and that tradition has stuck. When your great aunt is in town for the decoration ceremony, she likes to add a string of cranberries that weave through the branches, circling from the base to the tip. After the remaining ornaments and random decorations are hung, thin strips of silver tinsel are draped over the tips of the branches.
Let's try and define this in a way that is meaningful, by looking at the Christmas tree without decorations, first. We could define every aspect of every atom of the tree and account for quantum effects, like the memory file of a Star Trek transporter. This would be silly, though, as no two trees are alike, so it would be a fruitless excursion to find our defined Christmas tree. We aren't intending to transport our tree down to a planet; we just want an approximate tree to bring home to decorate. We might need to know the diameter of the trunk where it is cut, the height, the width, the density of the branches, the type of needles, etc. Perhaps there are ten or so aspects that are sufficient to capture that we could give to any person to select the tree we want. In ontological terms, this set of characteristics is a knowledge domain. Models of knowledge domains often look like trees.
With what we have defined so far, it is likely that in 2020 we could send somebody out to get our tree for us. If we forget something, the model is easy to add to without breaking other parts of the tree. Perhaps a tree lot starts up a delivery service, and we need to modify our model to account for it. We could just add another branch to the node tree lot that has pickup method "delivery". This shows another important part about this model. It has an open-world assumption. Just because we didn't list a delivery service on our 2019 model doesn't make it wrong or imply that a delivery service doesn't exist. We simply haven't defined it yet. The transporter definition is closer to a closed-world assumption. We better be very sure that our definition is complete before we try and re-assemble the human (or tree) we have beamed to the surface of the planet from our space ship. Open-world models are easier to collaborate on, as the model can grow interactively and be refined over time.
If we define the aspects needed to purchase cranberries, the knowledge domain is significantly different. We need to define color, firmness of the fruit, frozen or fresh, etc. Domains can also intersect. There is a sequence of things that we put on the tree in order: lights, silver globes, popcorn string, and, if your aunt is in town, cranberries. The sequence of things is a different domain. This domain might include things like who does what at what time and events like if your aunt is in town that change the sequence. This is an example of an intersection of different domains. In the end, after all is done, after we place the star on top of the tree and turn on the lights, we finally see the entire tree, all of the domains together.
The Christmas tree itself, without any decoration, serves as the defining domain for all of the other related domains. We can lay the other domains, figuratively and literally, around and upon the branches and trunk of the tree to form a handbook, a decorated tree.
Cruft Buster makes labels on the flow part of the handbook rather than capturing them as formal triples. Labels are put in the file tree next to the predicates. This makes the system simpler and more agile, as it focuses on getting the data flow documented and then hooking up the other domains. Documentation would normally be considered another domain; instead, Cruft Buster drapes the documentation over the top of the primary focus, utilizing the shape of the Christmas tree to form the shape of the documentation automatically. With all of the above introduction, this video shows how this works and also introduces the concept of zooming in on a process.
Handbooks can also be created around templates to generate handbooks modeled like design documents and technical specifications.