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.

Coin of My Realm: Meaning

I’ve been thinking on this tweet a bit lately. How do we determine what is the coin of our realm? What is important to us?

I wanted to expand on this tweet. Isn’t really “what others offer” is a question of what we value in ourselves, and in other people? Lets leave aside the fact that this is a transactional model of relationships. Instead, let’s focus on the value. If we really want to understand what we value, I think the real question comes down to time.

How do you spend your time? With whom do you spend it? Because, when it comes right down to it, the only thing each of us has of any value is who we are as people and how we spend our time. Everything else just expands our agency within that framework.

I have been spending a lot of my time lately doing writing, providing support via Discord & Telegram and doing some minor programming for a cryptocurrency called Ergo. I’ve learned a lot about:

  • How cryptocurrencies work
  • The psychology of people in the cryptocurrency space, which is indicative of people more generally
  • Learning to use new software tools

The last is an interesting development, I’ve never collaboratively worked on a project using git. I have use it to provide back-ups and versioning for my own work, such as configuration files, bash scripts and so forth. But, it’s a different experience to work collaboratively with someone else with it. The collaboration has value, independently of the code being created or the ideas behind it. This is something that is missed in the above tweet.

Things change so fast in the cryptocurrency space, and it is filled with people trying to make quick money. Or, “life changing money,” which normally means they can stop working and do whatever they dream of doing, perhaps driving cross country in a Lamborghini. Wen lambo? This is a question often asked, jokingly, but it is also serious.

Given the environment, integrity is very important because there is such a lack of it. Most people are hoping to strike it rich, which means there is a large pool of people that can be scammed.

Beyond the get rich environment, it is also interesting thing to note how little agency people have in the space. At the level of the cryptocurrency itself, there are wild price swings, and much of the variance is market manipulation. Imagine all the problems of the stock market, without most of the regulatory restrictions.

But, it is also clear that the restrictions that are in place are there to benefit certain people, just as much as they are to protect people involved. So, there’s a distrust of larger governance, particularly governance by a state.

In its place, in cryptocurrencies, you have governance by unelected bodies, software developers, investors and other interested parties. It’s never governance by people using the cryptocurrency, in any form whether it is democratic, the choosing of representatives, and so forth.

Best case, it’s a meritocracy. Often, these meritocracies have a benevolent dictator, and while they may wish for more user input, do not know how to move from where they are at to a system where people using the tool are deciding how it should be used and what capabilities to develop.

Without any kind of real governance and input into the decision-making processes necessary to be a functioning entity, discussion tends to devolve into who has the biggest microphone and who can shout down opposing points of view. You might say this is the defining feature of our times, when people have little agency over the things they care about.

One solution to this problem is to care about different things. If you limit what you care about to the things that you have agency over, then you don’t have to argue about it with other people. You can simply do the thing.

Of course, anything sufficiently large is going to require organization beyond mere individuals. But, moving our scope out that wide quickly limits our agency. Most of us scope our concerns so they are beyond any real action on our part. It’s why we develop what the Unabomber describes as surrogate activities, or things we do that serve as a substitute for real agency over things that matter. It’s why people decide to run marathons, climb corporate ladders, or whatever. We set goals such as these when life is unfulfilling.

Where can we find meaning? Where can we find agency? I think the answer to this question in our age is the same answer Voltaire gave in Candide: Il faut cultiver notre jardin, or tend your own garden. Narrow your concerns to a few people. People that show themselves to be unworthy of concern? Remove them from your garden. Spend your time and energy on projects you control and involve yourself in the lives of people you know around you.

Those people don’t need to be “insightful”. Gardens need shade as well as fruit, and every tree and plant can bring something different to the ecosystem. But, we need to thoughtfully engage with the question: what is the garden for? Is it to grow the biggest, best vegetables? Or, maybe there’s something bigger to be found there, such as meaning and agency.

Blog Diet: A Starter List For Your RSS Reader (Updated Spring 2022) by Warren Ellis

“People keep asking me where I find stuff, or where to start with an RSS reader.

I exported my subscriptions, and damn, there are a LOT of dead blogs out there. I’m actually shocked at how much of my list is now gone. (And how many sites have shut off their RSS!) Here is a selection of blogs from the list of ones I think are still active. Like I say, it’s just a bit of my active subscriptions list, but maybe you’ll find something you want to follow.”

-Warren Ellis, “Blog Diet: A Starter List For Your RSS Reader (Updated Spring 2022).” warrenellis.ltd. April 22, 2022.

Here’s a list of “best” free RSS Readers for 2022. I’ve talked about RSS Readers a bit here in the past and suggested some places to start. I’m used Nextcloud News, newsboat, and flym. I like newsboat quite a bit, but I find I don’t check it as much as if it is in a mobile app. YMMV.

Newsboat

Newsboat is the Mutt of RSS readers. Works and looks pretty much the same as mutt. In making the conversion, I learned that I have over 500 RSS feeds, which in combination with a few dozen newsletters via email is how I discover the material to post to this blog.

I used to use an app on my phone to scroll through when I had time, but I found using Newsboat sped up the process considerably. So, even though I have to sit down at the computer and go through each feed, Newsboat will be my default method moving forward. Recommended.

Fun With Fortune in Linux

Fortune provides a random quote or aphorism every time you open a terminal in Linux. I wanted to have a personalized fortune using zuihitsu quotes posted on this site come up whenever I opened a terminal. If you want to do something similar, here’s the procedure.

To check if you have it installed, simply type fortune into the terminal.

$ fortune 

This either returned a fortune or an error message. If you got an error message, then install fortune using the package manager for your system.

$ sudo apt install fortune-mod

Let’s create our own file of fortunes. I want to use my zuihitsu quotes I have posted on this site. This file is a text file that looks like so:

%
quote 1
%
quote 2
%
quote ...

There is a copy of the file available online.

If you have just a file with lines of quotes, this is easy to get into this format using emacs. Simply type: M-%, followed by c-q c-j Enter then c-q c-j % c-q c-j Enter. I like to check the replacements, so just keep hitting y to do the replacement and move on to the next one if it looks good. Save the file to the appropriate directory, which on Debian systems is /usr/share/games/fortunes, but can vary. For explanation purposes, we are going to assume the file was named zuihitsu with no file extension.

Note: If you are using the file above, just save it as a text file in your directory. Then, copy it to the appropriate system directory without a file extension.

Now, create a .dat file for the file you just made.

$ sudo strfile zuihitsu

Set the same permissions on the new files as the others in the directory. This just makes the files readable to groups and others.

$ sudo chmod og+r zuihitsu
$ sudo chmod og+r zuihitsu.dat

Following the rest of the directory. I added a symbolic link.

$ sudo ln -s zuihitsu zuihitsu.u8

You should be able to test it now.

$ fortune zuihitsu

Assuming that worked. The final thing to do is to have your preferred shell call this when it runs. I use bash, so I added the command above to my bash_aliases file. From then on, it will pull a random quote from the zuihitsu file every time you bring up the terminal.

Bonus

Make a fortune come up automatically every time you login or open a new terminal by adding the following to .bashrc or .bash_aliases:

fortune zuihitsu 

Also, if you use mutt, you can add the following to your .muttrc file to have this fortune file generate a random signature for your emails:

set signature="fortune zuihitsu -s|"

The -s selects shorts quotes and the | pipes it to your email text.

Did you know the original fortune-mod fortune collection is available as a EPUB?

Being a Creator, Craig Mod

This is a really interesting discussion of how one man created a business using a subscription model combined with discounts for the finished work for subscribers. There’s much to think about in this discussion. If this is of any interest to you, I’d read the whole thing and the previous year’s as well. He talks about what it takes, how much it costs, the tools he uses, and provides a whole lot of other detail that might provide some food for thought.