Documentation As Empathy

…Writing documentation is an exercise in empathy. We’re not describing an objective reality – the source code already does that. Our job is to help shape the relationship between users and the Vue ecosystem. This ever-evolving guide provides some rules and recommendations on how to do that consistently within the Vue ecosystem.

Principles

  • A feature doesn’t exist until it’s well documented.
  • Respect users’ cognitive capacity (i.e. brain power). When a user starts reading, they begin with a certain amount of limited brain power and when they run out, they stop learning.
    • Cognitive capacity is depleted faster by complex sentences, having to learn more than one concept at a time, and abstract examples that don’t directly relate to a user’s work.
    • Cognitive capacity is depleted more slowly when we help them feel consistently smart, powerful, and curious. Breaking things down into digestible pieces and minding the flow of the document can help keep them in this state.
  • Always try to see from the user’s perspective. When we understand something thoroughly, it becomes obvious to us. This is called the curse of knowledge. In order to write good documentation, try to remember what you first needed to know when learning this concept. What jargon did you need to learn? What did you misunderstand? What took a long time to really grasp? Good documentation meets users where they are. It can be helpful to practice explaining the concept to people in person before.
  • Describe the problem first, then the solution. Before showing how a feature works, it’s important to explain why it exists. Otherwise, users won’t have the context to know if this information is important to them (is it a problem they experience?) or what prior knowledge/experience to connect it to.
  • While writing, don’t be afraid to ask questionsespecially if you’re afraid they might be “dumb”. Being vulnerable is hard, but it’s the only way for us to more fully understand what we need to explain.
  • Be involved in feature discussions. The best APIs come from documentation-driven development, where we build features that are easy to explain, rather than trying to figure out how to explain them later. Asking questions (especially “dumb” questions) earlier often helps reveal confusions, inconsistencies, and problematic behavior before a breaking change would be required to fix them.
-Evan You, et al. “Vue Docs Writing Guide.” github.com. Accessed: November 16, 2022.

I have been thinking a lot about this writing guide over the last few days. It takes a lot of caring to produce good documentation, particularly as you learn something so that you can overcome the curse of knowledge. I think much of this can be applied to writing more generally.

Messengers

It seems to me that some messaging app that has the functionality of WeChat is where a lot of this web3 and cryptocurrency is going. The functionality of WeChat is described by Wikipedia as: messaging, public accounts (for famous people or people with an audience), channels for friend groups, digital payments, video, etc.

Right now, messaging is dominated by Facebook Messenger, WhatsApp, Telegram and Discord. I suppose Apple’s Messages is another, but I don’t know the Apple ecosystem.

The main piece will be the incorporation of digital payments. The above aren’t really positioned to deliver on digital payments, and they also have privacy problems.

  1. Signal: good option, people object that it requires ID verification through phone number registration. But, it already has digital payments incorporated through a build-it MobileCoin wallet in the app.
  2. Keybase: It has an Stellar cryptocurrency wallet. It’s more like groupware designed to verify users social media accounts, but it is in this space.
  3. Element: open source with paid tier option, no ID required. Less commonly used than Signal. No digital payments
  4. Threema: one-time payment for a license to use. Bills itself as maximum security. New to me. I don’t think payments are available.

Questions on Democracy & Ballots

  1. What’s the point of having a ballot with only one option and no write-in? Maybe offer abstain as the option?
  2. Why am I voting on judges and retaining judges?
  3. If you are going to make someone vote whether it is yes/no or no option, can we have a meta vote option where we select no for all judicial candidates and abstain in races where there is no choice?

These questions occurred to me while filling out my ballot today. Problem for No. 3 is the most likely meta option will be a straight-ticket option for partisans.

Accept, Reframe, Or Reject

“EVERYONE GETS SHITTY FEEDBACK sometimes. There are a variety of reasons for this, starting with the fact that giving feedback is difficult and most people are terrifically bad at it. But even those who have developed strong feedback skills will still sometimes do it poorly, because the attention and care required to do it well are so often in short supply; or because the systems we occupy do not incentivize the effort. All of this means that shitty feedback is out there, and while we can and should work to prevent it, we also need mechanisms for dealing with it when it happens.

A lot has been written about how to avoid giving bad feedback, but I want to tackle the flip side: what do you do with feedback that sucks?

-Mandy Brown, “Accept, Reframe, Reject.” aworkinglibrary.com. November 1, 2022

This is a variation of the truth that there are always three actions available to us for any circumstance. We can accept it. We can change it. Or, we can leave it. I’d argue that the vast majority of criticism from others is a commentary on their own issues. It often has little to no relevance to the person being commented upon. So, almost everything either needs to be reframed or rejected. The crucial question is: what can I learn from this criticism?

This piece talks about the first action. I think the most important point is to not defend yourself. It is rare that this is necessary, and it is often our first reaction. You can simply say, “Thanks for sharing your point of view. I’ll be sure to give it some thought.” You’ve not accepted that their criticism is valid. But, you have accepted that they have expressed their point of view. You have heard it. You are considering it. This is all most people want: to be heard and consideration.

Of course, there are situations where you have to do something different, such as the supervisor at work example she uses. But, even there a simple: “I’ll do better,” will often suffice.

Politeness costs nothing. Listening to people costs nothing. These can be effective avenues for getting feedback on our behavior from the outside world. But, it’s rare for a person to know us well enough to give feedback that can simply be accepted. This is true of even people that know us well. We all have different values and ways of looking at the world, and we need to reframe input to make it valuable in light of our idiosyncrasies. Feedback, particularly the unsolicited kind, almost never does that.

Also, people that you don’t know rarely give feedback worth considering. They are commenting without context, which is generally worthless.

Imagined Realities, Evidence & The Singular

“An ‘imagined reality’ is an addictive mental drug that humans are infatuated with. It cures the frustration brought about by the constraints of the actual reality. Like a physical drug, it could cure pain and make life in prison more tolerable, but it could also take away life if used excessively. It brings communities with a shared spiritual belief together but it can also lead to terrorism and hatred…

…Imagined realities can consume the oxygen in the room. Galileo was put in house arrest when the imagined reality of a geocentric world flattered the egos of the dominant forces in society. The lesson is not to promote hypothetical entities, like extra dimensions or wormholes, as the centerpiece of the mainstream of theoretical physics for half a century without a shred of experimental test for their existence. The best way to maintain a sanity balance is to adhere to experimental tests as our guide, first and foremost in physics. Physics is a learning experience, a dialogue with nature rather than a monologue. Our love of nature is not abstract or platonic, but based on a direct physical interaction with it.

-Avi Loeb, “For the Love of Evidence.” medium.com. October 30, 2022

“Patapsychology begins from Murphy’s Law, as Finnegan called the First Axiom, adopted from Sean Murphy. This says,and I quote, “The normal does not exist. The average does not exist. We know only a very large but probably finite phalanx of discrete space-time events encountered and endured.” In less technical language, the Board of the College of Patapsychology offers one million Irish punds [around $700,000 American] to any “normalist” who can exhibit “a normal sunset, an average Beethoven sonata, an ordinary Playmate of the Month, or any thing or event in space-time that qualifies as normal, average or ordinary.”

In a world where no two fingerprints appear identical, and no two brains appear identical, and an electron does not even seem identical to itself from one nanosecond to another, patapsychology seems on safe ground here.

No normalist has yet produced even a totally normal dog, an average cat, or even an ordinary chickadee. Attempts to find an average Bird of Paradise, an ordinary haiku or even a normal cardiologist have floundered pathetically. The normal, the average, the ordinary, even the typical, exist only in statistics, i.e. the human mathematical mindscape. They never appear in external space-time, which consists only and always of nonnormal events in nonnormal series.”

-Robert Anton Wilson, “Committee for Surrealist Investigation of Claims of the Normal.” theanarchistlibrary.org. February 20, 2011

There’s an interesting tension between these two views. Yes, having beliefs based on evidence is a good idea. However, evidence supports generalizations that do not tend to be true, it the absolute sense that Avi Loeb wishes to establish his views.

So, we need a healthy bit of skeptism. Some ideas are useful for living our lives. But, the trick is to reimagine them and discard ideas when they are no longer useful. We aren’t terribly good at letting ideas go, particularly when we have spent so much effort believing in them.

Perhaps the solution is to keep our imagined realities and identities small, and take care to be able to walk away from them when they no longer serve us well.

The Employment Interview

I was reading this tweet, and it reminded me that I used to use an interview template when interviewing people for positions. Still strikes me as a decent tool. I find it useful to have a framework for evaluating people, so you can focus on what’s important to doing the job well and can make use of the same standard of evaluation.

The people making the hiring decisions tend not to like this style. This reason is clear. People tend to hire people they like. This template led me to recommend people regardless of whether I liked them personally or not. I tend to be more skeptical of people that are engaging the first time I meet them.

Most of the ideas came from a single book, which one I have forgotten. I think this could also be a useful tool for preparing for an interview.

The Finite Pool of Worry Hypothesis

“According to Weber’s psychological theory of the finite pool of worry, people avoid dealing with multiple negative events at the same time. Consistent with this theory, as people worry more about the COVID-19 pandemic, they tend to neglect the problem of climate change. Here, we examine the number and content of climate change discussions on Twitter from 2019 through 2021. We show that as COVID-19 cases and deaths increase, climate change tweets have a less negative sentiment. There is also less content associated with fear and anger, the emotions related to worry and anxiety. These results support the finite pool of worry hypothesis and imply that the pandemic redirects public attention from the important problem of climate change mitigation..”

-Oleg Smirnov and Pei-Hsun Hsie, “COVID-19, climate change, and the finite pool of worry in 2019 to 2021 Twitter discussions.” PNAS. October 17, 2022.
119 (43) e2210988119.
https://doi.org/10.1073/pnas.2210988119

This is the first time I have come across the finite pool of worry hypothesis. It strikes me as a subset of the paradox of choice problem. As choices proliferate, the cognitive load of understanding the various tradeoffs in the options gets exponentially more difficult, and we have to find a way to reduce our choices and make a decision.

One way that we reduce our choice is by using Maslow’s Hierarchy of Needs. If we are worried about getting our immediate needs met and for our safety, then we will not have much room left over for worrying about climate change and its impact on future generations.

As we move up the hierarchy of needs, then we need to select between things to care about. How does plastic pollution and “forever chemicals” compare to climate change as an existential risk? It’s probably a safe bet that low probability existential risk not effecting people personally will get evaluated differently than something that has the potential to directly impact someone.

For example, the risk of climate change is evaluated differently, over time, depending on whether people think there is some relationship to climate change and the current risks they face. If you think ice caps melting might impact your coastal property in the next two decades, you might think about it differently than people 50 years ago did, when the discussion was of problems in 2100 CE.

Also, anthropogenic climate change is discussed differently than say climate change that happens due to meteorite impact or a supervolcano. Presumably, anthropogenic climate change includes issues of both of culpability and the view that it is under our control. We might not feel the same about the other two, and we may put it outside our sphere of concern.

This concept provides a lot of interesting food for thought.

N of 1 Experiment: Hafnia Alvei for Weight Loss

“An experimental probiotic aids weight loss in overweight people following a calorie-control diet.

Previous studies by Pierre Déchelotte at Rouen University Hospital in France and his colleagues suggest that orally administering the gut bacterium Hafnia alvei helps obese mice lose weight. The probiotic produces a molecule called ClpB that mimics the appetite-reducing hormone alpha-MSH.

Now, the researchers have found that the bacterium has similar effects in people who are overweight, presenting their results at the Targeting Microbiota 2022 conference in Paris last week.

The researchers counselled 212 people with an overweight body mass index (BMI) on how to reduce their calorie intake by one-fifth for three months. BMI is a measurement that uses your weight and height to calculate if your weight is healthy. The participants were asked to maintain their existing level of physical activity.

Over the three months, roughly half of the participants also took a pill containing H. alvei twice a day. The remaining participants took a twice-daily placebo. The people in both groups were of a similar age, height and starting weight.

Among those who took the probiotic, 55 per cent lost at least 3 per cent of their body weight, compared with 41 per cent of the people taking the placebo.”

-Carissa Wong, “Appetite-suppressing probiotic helps overweight people lose weight.” New Scientist. October 26, 2022

Procedure is fairly straight-forward. Take one capsule in the morning, one in the evening for 3 months. You can buy the capsules used online. Do it for science.

Simulated Selves

“This Mum and Dad live inside an app on my phone, as voice assistants constructed by the California-based company HereAfter AI and powered by more than four hours of conversations they each had with an interviewer about their lives and memories. (For the record, Mum isn’t that untidy.) The company’s goal is to let the living communicate with the dead. I wanted to test out what it might be like.

Technology like this, which lets you “talk” to people who’ve died, has been a mainstay of science fiction for decades…

…“The biggest issue with the [existing] technology is the idea you can generate a single universal person,” says Justin Harrison, founder of a soon-to-launch service called You, Only Virtual. “But the way we experience people is unique to us.” …

But she warns that users need to be careful not to think this technology is re-creating or even preserving people. “I didn’t want to bring back his clone, but his memory,” she says. The intention was to “create a digital monument where you can interact with that person, not in order to pretend they’re alive, but to hear about them, remember how they were, and be inspired by them again.”

-Charlotte Jee, “Technology that lets us “speak” to our dead relatives has arrived. Are we ready?” technologyreview.com. October 18, 2022

Advances in artificial intelligence are opening up new possibilities of creating virtual representations of people. It’s a kind of advanced Turing test, not of a machine intelligence being able to pass itself off as human, but instead, being able to pass itself off as a person that you know or had known.

If you provide enough data – in the form of video, voice and text – you presumably can approximate what a person might do or so in certain contexts. It becomes possible to create individual avatars or constructs that approach the real thing.

The first application is for people to process grief. It seems obvious that this will be a thing, where people will use this technology to capture people around them and keep them alive in a sense. As with most change, there are benefits and risks to consider. On one hand, it would be nice to be able to talk with and confer with digital avatars of people that have died or left our lives for one reason or another. On the other hand, it is easy to imagine that these “relationships” would become maladaptive, where they call upon the limited time that we have and prevent us from meeting new people and spending the time necessary to have meaningful relationships with them.

Beyond grief, I think, in some sense, we already have inner representations of people in our minds. For example, I will sometimes want to make a comment that lacks tact, I sometimes have a version of my wife in my head saying something like, “You can say that, but say it nicely,” which, in fact, is something my wife says to me several times a year. I’d guess a digital assistant version might be better than the version I have in my head who I could consult about the right way to handle certain social situations. But, then again, I could just ask her in person. Wouldn’t the digital version get in the way of the real person, and ultimately damage my real relationship?

I like the idea of having multiple versions of myself. I imagine the process of adding data to be much like working on a blog, where the process of documenting surfaces thoughts that you might not have had otherwise. It changes you.

Then, you’d be able to consult with a different version of yourself. You’d be able to check in with past versions, and see how you have changed. You could get second opinions, from a close approximation of your self. There are also hazards here because ultimately this is a past facing exercise, and temperamentally, I try to live more in the future, or in the moment, when I can manage it.

In any event, this is interesting food for thought. I’d expect using this technology at funerals or by people that want to live on in a sense beyond when they die to be common within the next decade or two. It’s probably useful to think about the various tradeoffs before then.

Sudowrite: Writing with Artificial Intelligence

Robin Sloan described a process for “writing with the machine” back in 2016 that I tried in 2019. The interesting part of doing it yourself is that you could select the corpus that the A.I. was trained on and get writing in that style of subspecialty. But, it took a bit of work to set-up correctly, and these text generative models have gotten a lot better with GPT and other efforts.

So, if you have never tried writing with A.I., and it will likely become a standard feature in word processors and text editors within five years or so, you can try Sudowrite, which makes the whole process easy to set-up and try out.