May 9, 2020

The Art of Explanation

Notes for book The Art of Explanation: Making your Ideas, Products, and Services Easier to Understand

Context

Explanation requires empathy. You have to think like your audience.

Explanation lowers cost of understanding. We have a short attention span and have to utilize others time efficiently. Must not waste audience’s time.

Explanation is a way to package ideas.

Explanation answers the question “Why?”

Explanation makes people care. If the user knows about an idea only then he/she would be able to care about your product.

Sometimes we want to appear smart and use difficult to understand explanation which only an expert would understand. The audience which does not know about the expert talk would be lost.

Why current way of explanation fails

Incorrect assumption about the audience knowledge.

Should change the explanation according to the audience. If you’ll use the expert talk to explain something to beginners, then their confidence would erode and then they won’t be interested in the explanation because they are not able to catch up.

Categorizing your audience

We can divide people on a scale of A to Z to denote how much they know about the idea. A means no knowledge, Z means expert.

People on the Z side are very knowledgeable but have curse of knowledge. Because they have so much knowledge about the subject, they are not able to know what it would be like for a beginner to understand this.

Package the explanation

Context is important for people to get used to the idea and see the bigger picture. Usually people at A side need more context than people at Z side.

The people at A size need to know about the Why more than the How. The people at Z side are already aware of the Why and need to understand How does the idea is implemented.

Simple stories are more effective for explaining something because we can add the user to be a part of the story in understanding the idea.

Storytelling is more appropriate near the A level.

Make connections to any other things that the user might already know. Whatever you are doing, there is a very high chance that you can relate it to some other idea. Can make connection by comparing it with some other competitor. This way is also used to learn effectively.

As we move towards the Z scale people, we have to focus more on How instead of Why. So we might have to add recipe style explanations for the How.

Simplify the idea.

Constraints are good. When we have too many options we tend to get confused and not choose anything. Whenever trying to explain anything, try to work with some constraints.

Present the explanation

• state intention
• solve a problem
• reduce noise
• embrace imperfection

Visuals are an important part of any explanation. You can explain something very easily by a photo which could be very difficult to explain by words.

Visuals are attractive and get attention.

No need to have fancy visuals. Can explain using simple drawings.

book notes

March 15, 2020

Debug when stdout and stderr not available

I am working on a blessed application. Sending console.log output to standard output and error stream messes up the terminal because blessed is already drawing stuff.

This is my solution for this problem.

/* eslint-disable no-console */
import { Console } from 'console';
import * as fs from 'fs';
import * as path from 'path';

const output = fs.createWriteStream(
  path.resolve(__dirname, '../stdout.log')
);
const errorOutput = fs.createWriteStream(
  path.resolve(__dirname, '../stderr.log'),
);

// Custom simple logger
export const debug = new Console({
  stdout: output,
  stderr: errorOutput,
  colorMode: true,
});

console.log = debug.log;
console.info = debug.info;
console.error = debug.error;

I have created a new console instance and piping the stdout and stderr to 2 different files.

By changing the reference of console.log to debug.log, we are able to send the streams to the files specified.

So if we or any other module uses console.log or indirectly writes to the stdout or stderr, then we’ll get those stream written to our files.

For checking out the stdout and stderr I open 2 instances of terminal and run these 2 commands in each:

tail -f stdout.log

tail -f stderr.log

node.js javascript