Gather | Sources and Feedback
Instead of merely capturing knowledge of the system in a normal written language, which varies in meaning with specific language and participants, Cruft Buster captures knowledge with conventions that allow immediate visualization and analysis, as well as an ability to delegate and collaborate. The meaning of the knowledge can also be pinned to agreed on ontologies. These topics will be explained briefly on this site. Rather than get too bogged down in them, these are illustrated with working examples and external references. While Cruft Buster is not as comprehensive as a formal enterprise architecture (EA) like TOGAF®, it is cognizant of EA's goals, and compensates for constraints by using machine learning techniques to gain visibility and relationships across alternate views of the system. All of the tools and methods are part of current GNU/Linux distributions, and this is documented on SysAdminTools. If this is gibberish, please be patient. It takes some time to learn the model of a new way to model systems.
To kick things off, this website itself uses the same method (I'm selfdogfooding). Rather than obscuring the data in a database that has to be available and maintained, the structure of the website lives on a plain old filesystem in directories. Here it is:
├── 0 │ ├── 1 │ │ ├── 1 │ │ │ └── narrative.md │ │ ├── 1.details.txt │ │ ├── 1.title.txt │ │ ├── 2 │ │ │ └── narrative.md │ │ ├── 2.details.txt │ │ ├── 2.title.txt │ │ ├── 4 │ │ │ └── narrative.md │ │ ├── 4.details.txt │ │ ├── 4.title.txt │ │ └── description.md │ ├── 1.title.txt │ ├── 2 │ │ ├── 1 │ │ │ └── narrative.md │ │ ├── 1.details.txt │ │ ├── 1.title.txt │ │ ├── 2 │ │ │ └── narrative.md │ │ ├── 2.details.txt │ │ ├── 2.title.txt │ │ ├── 3 │ │ │ └── narrative.md │ │ ├── 3.details.txt │ │ ├── 3.title.txt │ │ └── description.md │ ├── 2.title.txt │ ├── 3 │ │ ├── 1 │ │ │ └── narrative.md │ │ ├── 1.details.txt │ │ ├── 1.title.txt │ │ └── description.md │ ├── 3.title.txt ├── description.md ├── footer.html ├── header.html ├── mid_first.html ├── mid_second.html ├── purpose.md ├── terms.md └── title.txt
This same structure, the tree model used every day on a computer filesystem, can be used to create models of complex systems. The knowledge can either be gathered and stored directly in a tree with this convention, or it can be gathered as triples (more on triples later). What makes this method different, is that the structure is understood and accessible without sophisticated tools.
Before gathering knowledge, here are some important things to be aware of:
If useful, create a template for various collection efforts. This is discussed in Handbook.
Talk to people as much as possible and as soon as possible.
Don't rely solely on automated discovery. While it is often possible to use automation to demonstrate completeness of analysis, it requires human focus and interviews to gather the correct information.
Don't sink a bunch of time into a system that is not an important part of the organization. Ensure appropriate effort by talking with people and soliciting frequent feedback.
While these articles are sequenced in a logical manner, it is important to read through all pages for perspective and vocabulary. I try to be DRY. WET=Cruft
The first step, after initial interviews and discovery, is to determine the primary focus for the handbook. Knowledge will be gathered around this form, in accordance with the schema. The primary focus is a way of looking at a system where the subjects are related in the same way.
The knowledge is captured in the form subject-predicate-object (triples). This means that the subject has some kind of relation to an object. The meaning is the same as when used in language. Bob loves Alice, for instance, means Bob (subject) loves (predicate) Alice (object). The benefit of this approach is that existing tools can be used to immediately visualize and query the gathered knowledge. Additionally, triples can be used that reference live ontologies, so that meaning and relationships are already known and agreed on.
As an example, let's consider a simplified water distribution system.
In this case, the subject is the diameter of the pipe, and the common relation between subjects is "Transition to". Imagine an entire public utility along these lines. A reservoir in the mountains might have a very large pipe, as would an aquifer. At the furthest point in the system the pipe would be much smaller as it enters a customers house. We could model the entire system around the pipe diameter and this would be our primary focus.
Once the primary focus is established, gather these items, as appropriate, * required:
* Hierarchy of numbers (primary focus) from 0 on down: level 0 should be high enough, and worded such, that anybody in the organization understands what it means. The numbers are always the subject in any documented relation; however, it is useful in interviews and documentation to use numbers, as most people are already familiar with numbers-as-hierarchy. 3.1.6 means 6 is a subprocess of 1 which is a subprocess of 3, for instance. In the water distribution example, the 15 cm pipe would be 1, and the 10 cm pipe would be 1.1.
* Title of subject and objects: in documentation this is the title of a section. On a diagram this is the label on the node. This should generally be short. For diagrams, insert \n between lines, and this will split lines for node labels yet treat them as a single line for narrative documentation.
Detail of subject and objects: this is added description about the subject that is displayed at user request on diagrams, and as a supplementary description of the title on narrative documentation.
Descriptions at the first level of the hierarchy: this is generally the category in a narrative, or the nodes on level 0.
* Relations between subject and object: this depends on the primary focus and the set of predicates.
Detail of the relations between subject and object.
Use IT Docent as a handbook example, Tributary Software for software, SysAdmin Tools for operations, and Are We Resilient? for ongoing features, example domains, and new models. [Note that these sites are a work in progress that I am writing at the same time as I am developing and documenting the methodology, so they are in varying states of completeness and function.]