Misconceptions about Memory and Good Documentation
Documentation probably is one of the most important tasks that no one has time for. I also overlook the importance as I get swept by a series of projects and requests. Recently, however, I learn more and more about the importance of documentation in areas other than computer science and wanted to summarize my understanding of human memory and delve into few tricks on how to improve our documentation to safeguard from few failure modes of human memory.
Memory is a Noisy Reconstruction Process
Memory is a very subjective experience that can vary from a person to person even for the same event. Such subjective experience might emphasize different parts of the event or completely miss the details. You might be familiar with how people when asked to count the details of an event completely misses that there was an unusual event happening in the scene, a well-known case is illustrated in the Monkey Business Illusion.
Although you might think you know some details of an event, you could miss some events and yet you could be confident that you know. This is a well-known example and I want to list other types of memory errors.
Another example of the failures in our memory is well illustrated by The Innocent Project in New York City, a social group focusing on the exoneration of innocent people, many of whom were incarcerated purely based on the eyewitnesses. By 2013, after almost two decades after its inception, the Innocent Project vindicated 310 innocent people who spent on average 13 years in prison through DNA testing, which were not readily accessible during the trial.
Memory Bias
The memory reconstruction process is a very subjective experience 1. This process reconstructs the same event in a different context for the same person depending on his/her knowledge and experience. If one is familiar with a certain predefined concept, then a similar event with different details would be reconstructed to match the predefined concept rather than remembering the details accurately. From the information processing point of view, I think this is a very good compression mechanism that encodes and decodes the information using the most efficient compression, although it fails to capture details. In other words, my interpretation of such memory bias is that, if our experience or concepts can create basis functions of an event, then we can compress information easily, memorize faster by combining the existing basis rather than creating new basis functions for new events.
However, this creates a bias towards our own experience and knowledge and makes the memory match such existing concepts and thus distort our memory. Another good example is UFO sighting, the Loch Ness Monster, the Big Foot, etc. When some concepts become popular in the media, people are likely to memorize things to match the known concepts. After the word UFO became popular, the number of UFO sighting increased dramatically.
On the other hand, if we can interpret our findings, experience, or knowledge, using existing or well-known concepts, it would be easier for the readers to remember the new concepts.
Confidence $\not \propto$ (not proportional) to the Accuracy of Memory
When someone remembers events with conviction, we tend to give higher weights to such testimony. However, researchers 2 have found that there is a weak correlation between the confidence of testimony and the accuracy of a memory. Some paths reinforce such phenomenon. Post-identification feedback 3, which creates a positive feedback loop enforcing the confidence of recollection but not the accuracy, is a well-known phenomenon of such an example. We decode and re-encode our memory repeatedly and we overwrite our memory which can create noise in the process. False memories is another good example where a subject recalls inaccurate details of an event that never happened. Loftus et al. 4 showed that you can easily create false memories in others by asking about an event that could have happened such as being lost in a mall as a child. Another example is “lying alters memory” 5. When we tell ourselves lies repeatedly, at some point, we start to believe our own lies. Anna Anderson who claimed to be Princess Anastasia of Russia is a good example of how a person can perpetuate a lie and later believe her lie to be true.
Generalization
Our memory degrades over time, loses details, and becomes semantic (broad and generalized). Some rat experiments show the generalization of episodes that reinforce one another in different contexts and distills the concepts quickly 6. This process allows vertebrates to quickly find connections, but problems arise in our complex social setups, which is well summarized in Lacy and Stark 7.
However, a problem arises with the notion that learning is occurring at this point and that it does not clearly discriminate between the current event and retrieved information from specific prior events or from generalized expectations of what should happen in such an event. As a result, whatever happens in this event becomes associated not just to elements that are actually present, but also to what we expect to be present based on our prior experiences and biases.
Exposed to a certain stimulus, we can generalize a certain object to perform a certain activity and such generalization can confuse when faced with different output.
Visual Hallucinations
This might not particularly fit the memory failure, but I think this topic could give us some insights into why our brains work in certain ways. Visual hallucination is “the perception of an external visual stimulus where none exists” 8. The simplest form of such hallucination, which is probably not considered a hallucination, can be seen in the blind spot, where we do not have any sensory input, but our brain interpolates the region so that we don’t sense the interpolated data unless we examine it closely. Another more pronounced case of visual hallucination is the Charles-Bonnet Syndrome, which causes people with a decreased vision to have visual hallucination. Our brain creates hallucinations to fill out the information gap and the basis of such hallucination is our experience and knowledge.
Writing Good Documentation
We discussed a few types of memory errors in our brains in this post. The common theme of our memorization process is that we encode information based on knowledge and experience and decoding the stored data can influence other existing memory. Also, by decoding and reencoding our memory, we can inject noise into our memory. There are few things that we can consider while writing documentation. First, to make the documentation or API memorable, we should make use of existing concepts or knowledge. To do that, we also have to know our target audience to know their knowledge and experience. Lastly, writing good documentation takes time which is also a big factor so we should focus on maximizing noiseless information transfer with the minimal documentation that can transfer the knowledge.
A few important things that we should consider include:
- Know your audience
- Do not spend too much time documenting knowledge or concepts familiar to the audience
- Spend more time on parts that your audience is not familiar with
- When introducing a new concept, create connections between concepts your readers might be familiar with by highlighting the difference
I think this is a pretty short list and quite an obvious one, but I think looking at this list again after learning how our brain memorizes gives a more concrete rationale on why we should write like this.
References
](https://www.tandfonline.com/doi/full/10.1080/09658211.2017.1340286)
Eyewitness memory of a supermarket robbery: a case study of accuracy and confidence after 3 months ↩
“Good, you identified the suspect:” Feedback to eyewitnesses distorts their reports of the witnessing experience ↩
[When lying changes memory for the truth ↩
Generalization of contextual fear as a function of familiarity: the role of within- and between-context associations. ↩
The Neuroscience of Memory: Implications for the Courtroom ↩
Leave a Comment