Relational Documentation

Think of something, any thing/idea/process you want, it doesn’t really matter. Now tell me, does the thing you are thinking of exist in complete isolation? Can you fully understand it without understanding at least a little bit about how it is composed or what it’s purpose is? Understanding anything isn’t possible without some context. Why does this thing exist? What other things work with this thing to accomplish the previous question? How is the thing composed?

Let’s say you were thinking of a car. What would you write in a user manual for a car? Why does the car exist? To quickly and efficiently transport humans and cargo over wide range of distances. How does a car do this? By combining (usually, for now) an internal combustion engine with a sturdy frame on four wheels. This is good documentation for a car, we have answered the big why and how questions surrounding a car. Why do humans and cargo need transported over a wide range of distances though? How does an internal combustion engine work? What other forms of transportation can provide the same type of service as a car? What else is powered by an internal combustion engine? To find those answers you need to find several disparate documents explaining those concepts. There are systems that do this to a certain degree (wiki) but the relationships exposed are erratic and unclassified in terms of why a concept exists or how it is composed and the links are not guaranteed to be bidirectional despite their actual relationship. This may be fine for a car since American culture has ingrained a lot of the ideas around the car into us but why do we maintain disparate pieces of documentation for concepts or systems that work together to form a cohesive body of knowledge? Why does each department of an organization or maybe even each team within a department maintain their own documents disconnected from the rest of the organization?

What I’m trying to say is what if we were able to get more out of our documentation by knowing the type of relationships it has to other pieces of documentation? Now ultimately, there are no boundaries in that scenario. Everything has some type of relationship to everything else that forms the reality we live in made possible by quarks (one could probably argue that there are bigger concepts than reality and smaller components than quarks but I needed to set the boundaries somewhere). But there are clear boundaries around why an organization exists and the smallest building blocks the organization uses to accomplish their goals. So what insight could an executive glean from tracing his strategic objectives down to the processes executed by his entry level employees? What productivity gains could the entry level employees achieve if they understood the broader picture for how their efforts contributed to the overall goals of the organization? How thoroughly could a student understand the materials presented in a course if they knew the relationships and their types between every concept presented?