Know Your System

I believe there are 3 things you need to know to interact with any system optimally:

Knowing how the system was intended to work can help in finding the optimal way to interact with it. If you work with a system with the designer’s intentions in mind, you can take a path that is compatible with their future plans, and even their oversights.

Knowing how people think the system works will help you understand other people’s uses of the system (or even your own!). You can see why they made the choices they made, and see past how what they did actually interacts with the system to what they intended.

Knowing how it actually works can allow you to do things that the designers claim are impossible. It can also help you work around unintended bugs. You can even contribute back to improve things.

When these three diverge

When these 3 views diverge significantly it is a sign of a significant problem with the system. While it is possible that a divergence could be the result of inexperienced users or inadequate training, I would argue that the issue almost always falls on the system itself. If people think the system works in a way that is drastically different from the creator’s intent, or the actual behavior, then the creator has either failed to explain the system properly (through bad documentation, variable naming, ui, etc). Or, if the author’s intention differs significantly from the actual behavior then they have made mistakes during creation. In either case the resulting system is a bad fit for the users.

Learning each viewpoint

Collecting information to build up understanding from each viewpoint can be complex, or even at times impossible. There are a few good places to start for each.

Learning how it was intended to work

Learning how the system was intended to work is, fundamentally, an investigation, not of the system, but of its creators. Read documentation or tutorials written or provided specifically by the creator. Examine the creator’s other work. Read their other writing. Watch or if possible attend their public speaking engagements. Review past advertisements for the system. If the system involves code, read the code comments if they are available. Read responses to bug reports. But above all else, the absolute best: speak directly with the creator.

When engaging with the creator learn as much as you can, but also be respectful and understanding. Communicate without judgement. Even if you disagree with them on fundamental points, be compassionate. You will get more and better information this way, and you will build rapport for discussing possible improvements once you have a better understanding.

Learning how people think it works

Learning how others think the system works involves engaging with other users of (or participants in) the system. Just as with the creator, the absolute best option is to speak directly with these users, and, even better, watch them use it! When that is not possible, review any evidence they leave behind. Read their reviews and blog articles. Watch recordings of them using the system. If the system is code, read any user code written against it. Read the bug reports they’ve filed.

While this is most important for understanding their uses, it can also give you new ideas for how to use the system yourself. It can also expand your thoughts for the next part.

Learning how it actually works

Learning how something actually works is both the easiest and the hardest of the three types of understanding. It is easy because it is the most possible. The creator may be completely unknowable, there may be no other users, but the system must be present. It is the hardest because this, above all of the others, is an attempt to grok the system.

Fundamentally the best way to learn how something actually works is to use it. A lot. However there are quite a few other things that you can do to make progress here.

Play scientist: write some hypotheses about how you think the system might work and test them. Explore the edges and limitations (incidentally allowing people to do this is one of the reasons that psychological safety is important to the success of an organization).

If the system is software, read the code, or if that isn’t available, decompile it. Also do debugging as much as is possible. This is something that is incredibly easy for some systems but not so much with others, but it is always (as far as I know) theoretically possible.

For reading code, a couple of other notes: Reading code is a skill and an active rather than a passive activity (I remember reading a good blog article on this but my brain, seemingly incorrectly, ascribed this to Paul Graham. So I can’t find it.). Do some refactoring to match your thought processes. Rewrite some of it without looking and compare what you wrote to what is actually there. Move it around. Meditate on it.

Dealing with discrepancies and creating change

When you find significant discrepancies, take care. Ensure that you have as complete a picture as possible. If you confirm, with a comprehensive understanding, that there is indeed a discrepancy, as stated earlier, this is almost certainly a manifestation of a problem with the system. You can, and should, do something to at least attempt to improve this situation. Perhaps you are the creator, or you have access to the creator. Respond to or communicate your findings to improve the system itself. Alternatively, add to the public understanding of the system by writing your own articles, creating videos, leaving comments, etc.

All systems are imperfect, and therefore there will be discrepancies. Once you have done your best to address the problems you discover, some will remain. Nevertheless, simply being aware of these issues will benefit you greatly. You will be able to work around these problems by avoiding them, and assisting others when they encounter them.

Notes and Asides

This was originally titled Know Your Framework. I had intended it to be specifically about working with frameworks in software development. I have found during writing that this approach will apply just as well to just about anything. Therefore I have expanded it out generically to systems in general. I still believe that the greatest application of this, for me personally, is in coding, because it is what I do professionally.

As a short aside, in the world of literary criticism I believe these 3 view points are quite common, although many have traditionally approached literature using only one of the three view points at a time. The comparable view points in literary criticism are author focused, audience focused, and text focused criticism (the last being proposed by The Death of the Author). Works of literature are, fundamentally, systems to be interacted with and understood. So it feels right to me that these are also common ways to approach literary criticism.

Edit 2023/02/10 - Adjusted notes and asides to include the original title. Hopefully this will make it easier for me to find this page via search moving forward.