The Opposite of Documentation is Superstition
Yes I know I'm technically on vacation but if I go too long without writing I die from a witch's curse and I don't want to work on longform projects For Reasons so here, have a newsletter post.
I take a lot of handwritten notes. This used to be with actual pencil and paper, but for various reasons I now use a Surface Go running OneNote. It's worse in some ways but better in just enough to be worth it. One thing I thought would be nice, but turned out to be fairly limited, is the "ink to shape" feature. You draw a freehand square and it converts it into a square shape. It's kinda janky, and doesn't always get stuff write, but it's often enough to be useful.
It will not convert things that look like straight lines into straight lines, or let you draw nice arrows. This makes it more limited than I want, making it less useful. Until yesterday when I was doodling and it suddenly turned a scrawled line into a line segment.
I experimented a bit and I can kinda get it half the time, except I have no idea why what I do works! You have to add a little glyph to the end, it seems, but what shape is the recognizer looking for? No clue. And can this give me arrows, too? Also no clue. I tried a bunch and didn't get any arrows, but I also tried a bunch for years to get line segments and didn't get those.
Where can I find the list of shapes that OneNote can recognize? Nowhere! This one-minute video is the only documentation for the feature. There's no way for me to find out what I can draw. There's no way for me to find out if shape X is something OneNote can't recognize or just something I'm consistently failing to draw properly. There's no way for me to know if my line-segment glyph is actually the intended way or just coincidentally close to the proper way. The feature is a black box and I only know what has and hasn't worked.
In 1948 BF Skinner tried a new pigeon experiment: instead of feeding them in response to certain actions, he fed them completely at random. By the end of the experiment, six of the eight pigeons developed nonsensical "superstitions" to get food:¹
One bird was conditioned to turn counter-clockwise about the cage, making two or three turns between reinforcements. Another repeatedly thrust its head into one of the upper corners of the cage. A third developed a 'tossing' response, as if placing its head beneath an invisible bar and lifting it repeatedly. Two birds developed a pendulum motion of the head and body, in which the head was extended forward and swung from right to left with a sharp movement followed by a somewhat slower return. (wiki)
I feel like one of those pigeons right now. I could totally see myself coming up with rules that I thought influenced a completely random process. But you know what would stop me? Knowing it was a random process. Being able to read some documentation that says "this is a random process".
Same with the "Ink to Shape". I can feel myself getting more superstitious about those lines. A line drawn just this way will turn into a line segment shape, a line drawn just that way won't. Despite them being the same line, drawn in the same way. I'm inventing justifications for why they're secretly different.
Please, for the love of God, write more docs. Don't let me become a crazy person.
¹ Caveat: the superstition explanation is pretty controversial and lots of behavior scientists think that Skinner read way too much into it. Some people have failed to replicate these results, while others succeeded. Consider this more a fascinating story than hard evidence.
If you're reading this on the web, you can subscribe here. Updates are once a week. My main website is here.
My new book, Logic for Programmers, is now in early access! Get it here.