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.

Creative Immiseration

“These tools represent the complete corporate capture of the imagination, that most private and unpredictable part of the human mind. Professional artists aren’t a cause for worry. They’ll likely soon lose interest in a tool that makes all the important decisions for them. The concern is for everyone else. When tinkerers and hobbyists, doodlers and scribblers—not to mention kids just starting to perceive and explore the world—have this kind of instant gratification at their disposal, their curiosity is hijacked and extracted. For all the surrealism of these tools’ outputs, there’s a banal uniformity to the results. When people’s imaginative energy is replaced by the drop-down menu “creativity” of big tech platforms, on a mass scale, we are facing a particularly dire form of immiseration.

By immiseration, I’m thinking of the late philosopher Bernard Stiegler’s coinage, “symbolic misery”—the disaffection produced by a life that has been packaged for, and sold to, us by commercial superpowers. When industrial technology is applied to aesthetics, “conditioning,” as Stiegler writes, “substitutes for experience.” That’s bad not just because of the dulling sameness of a world of infinite but meaningless variety (in shades of teal and orange). It’s bad because a person who lives in the malaise of symbolic misery is, like political philosopher Hannah Arendt’s lonely subject who has forgotten how to think, incapable of forming an inner life. Loneliness, Arendt writes, feels like “not belonging to the world at all, which is among the most radical and desperate experiences of man.” Art should be a bulwark against that loneliness, nourishing and cultivating our connections to each other and to ourselves—both for those who experience it and those who make it.”

-Annie Dorson, “AI is plundering the imagination and replacing it with a slot machine.” Bulletin of the Atomic Scientists. October 27, 2022

Strikes me as another example of the two computing revolutions. One is to make things easy with a touch interface. The other requires having deep knowledge of a complicated topic, such as building machine learning models – not to mention having the resources to do so at the highest level.

The point I would make is that creativity by proxy is still creativity. You may not understand how the A.I. generates its content, but we still can have an aesthetic sense about what is good and what isn’t that the A.I. doesn’t provide.

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.

The ABC of Contemporary Capital by David Harvey

1 of 13 Presentations on the ideas of Marxism.

“As a part of this course, I’m sharing rough drafts of pieces of a manuscript I am working on, a sort of textbook on Marx’s political economy.

I’m experimenting with crowd sourcing the revision process.” 

http://davidharvey.org/2022/01/new-course-the-abc-of-contemporary-capital/

I’ve talked about Hypothes.is for annotating in the past. I haven’t watched this particularly series, but I have read some of Harvey’s books and have found them useful. Bookmarking for later.

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.