Gather | Schema
Sources and Feedback explains the basic structure of captured knowledge, but the physical schema is quite simple, and is stored on a filesystem as folders and files. The schema is extensible by nature, as it is an open-world ontology. One of the advantages of constraining the model to a tree on a filesystem with symlinks, is that it helps contain the graph so that it isn't unwieldy. Another advantage is that it can be checked in to version control systems like git. Finally, trees are a familiar model.
The Cruft Buster model is flexible enough, even in this constrained fashion, that it can handle deep data flow diagrams. Here is an example of a system that uses data flow as the primary focus, rendered as a diagram, with the mouse pointer hovering to show the detail of the data flow between process 1 and Mail Room Staff:
Here is an example of a subset of that same information stored on the filesystem:
The overall logic of the schema is that items needed to generate a visualization of a level are stored at that level on the filesystem. Live rendering is a requirement for easy collaboration on a living document, and the schema facilitates this.
The primary focus is represented by numbers, and the hierarchy is captured via subdirectories off of the root. The root is a directory on a filesystem with 0 as a subdirectory. 0 is the first level of the entire set of knowledge, the domain.
Files with .md extensions are in markdown. Files with .txt extensions are in text.
The root includes files about the domain, including title.txt and description.md.
At level 0 the categories are listed. In the above example, 6 is a category called Customer Relationship Manager, which you can see live here. root/0/6.title.txt in the example contains "Customer Relationship Manager"
The idea of categories is to organize documentation for the handbook, which is arranged around the primary focus. This takes some getting used to, as the terms change, but it allows parallel development of a written handbook and a model of the primary focus at the same time.
Subjects are always numbers, and predicates are subdirectories with relative symbolic links to the object.txt file, which serves as the title file for the object.
has_tag is a special predicate that links back to the common tags directory under 0. The tags directory has tags with .md extensions that can hold descriptions, but this is optional for a tag. An example of a tag in above is plant_maint.md.
Here is a more detailed schema with mappings to an example filesystem implementation:
A fully populated schema for IT Docent is available on Tributary Software, as well as the Python scripts that generate IT Docent. This is a great way to learn more about how the schema looks in a complicated system.