DEV Community: Shaoqing Tan

Present with narratives

Shaoqing Tan — Tue, 06 Apr 2021 23:09:18 +0000

1. Why talk about presentations?

In teams large or small, meetings often start with a presentation. I sometimes lose attention amongst the slides, because I couldn't understand their relevance to the thesis. It's especially bad in technical design reviews due to the large amount of new information presented. In my opinion, we can improve the audience experience, thus the overall effectiveness, of these meetings by implementing a narrative in the presentation.

2. What is a bad presentation like?

For example, the team is considering replacing their database with a SaaS offering, and Kevin is assigned to find out more. Kevin designs the migration and he calls a design review with the team.

Kevin starts the presentation with a block diagram of the SaaS solution.
Kevin explains the solution details from head to toe.
The audience start to discuss performance, pricing, and scalability.
The audience revisit the solution details to find evidence to support their arguments.

In this case, the audience might be disengaged in step 2 because they struggle to digest the details of the solution without context. They wait for Kevin to finish the presentation so the discussion can start, then they end up needing to digest the details in step 2 again to finish the discussion. In other words, Kevin's organization of the material is ineffective such that the audience need to spend extra effort connecting the dots. Lets call this a subject oriented presentation.

3. What is a good presentation like?

Kevin could reorganize the presentation to mix in the context with the solution details, and demote inconsequential details to the appendix for the audience to review later if they so choose.

Kevin starts the presentation with a block diagram of the SaaS solution.
Kevin explains the performance is better (or not) with details.
Kevin explains the pricing is better (or not) with details.
Kevin explains the scalability is better (or not) with details.
The audience discuss performance, pricing, and scalability.

In this case, the audience can better digest the solution details, and are also better prepared for the discussions that follow. The meeting is more fluent and requires less effort from the audience. Lets call this a narrative oriented presentation.

4. What is a narrative and why is it better?

A narrative is a storyline in the presentation that the audience can easily follow, it connects the material and promotes effective discussions. A narrative oriented presentation creates and satisfies the train of curiosity of the audience, keeping their precious attention on what matters. It's UX design applied to meetings, where the audience experience is optimized. The presenter needs to see in the audience's perspective to break down the subject, separate the concerns, remove the confusions, and iterate for the best narrative. Subject oriented presentations are easier to create, whereas narrative oriented presentations are easier to receive.

5. How to practically create narratives?

I don't think I am "great" at giving presentations in meetings, but I do think the following tips are worth a try.

a. Create emphasis

What do the audience care about? What information do they need to carry out the discussion? The trick is to feed the audience important information in a simple way with just enough context such that they can digest it quickly, with unnecessary details omitted. The presentation should contain a series of emphasis instead of a full blueprint.

b. Break the subject

To accommodate the delivery of the narrative, details needs to be distributed according to the emphasis of the narrative instead of their natural structure. Imagine in our example, the SaaS offering handles floating point numbers and variable length strings, and they affect performance and scalability respectively. It's natural to put these two details together in a section called "data types", however it's more effective to split them into the "performance" and "scalability" sections.

c. Review and iterate

When the entire narrative takes shape, early parts of the narrative might have drifted and become inconsistent. Make sure to review and iterate until the narrative is rid of contradictions, confusions, and complexities.

d. Add the opinions

Opinionated narratives promotes more response in the audience. The opinion may end up being incorrect, but it makes the ensuing discussion more productive. Instead of saying the SaaS offering has 2 pros and 2 cons, say the SaaS offering is more competitive because it possesses the key advantage. The audience may disagree right away and start contemplating an argument, therefore warmed up for the discussion.

e. Ditch the slides

Slide decks enforce artificial breaks within the narrative, taking away the flexibility in arranging the material. If you are like me who presents in team design reviews instead of conference keynotes, there is no requirement of a slide deck, why put in the effort? I prefer a infinitely scrolled formatted doc, like a Google Doc.

f. Promote the questions

Instead of using nouns as headings, use either questions or imperatives. The narrative will be more explicit and the audience will understand what is the take away. If there are questions the audience are expected to have (e.g. how much does this cost?) or questions the presenter wants discussed, make sure to include them as well.

g. Shorten the sections

In each section or following each question, make sure the material is short enough that the audience can read through it without losing focus. A meeting presentation is not a Ph.D thesis, the audience has very little time for digestion. So if a section is long, break it. Making material references in discussions will also be easier if sections are short and numbered.

h. Read silently

Subject oriented material needs to be narrated by the presenter, whereas narrative oriented material is essentially the script the presenter will read out loud. Because of this quality, we can ask the audience to read the material in silence instead, they will digest the material better controlling their own pace. A silent reading ceremony at the start of the meeting also frees the audience from having to read the material beforehand, and it's something I learned from Amazon.

More on my blog: https://bettercallshao.com/present-with-narratives/

Organize your command life

Shaoqing Tan — Thu, 26 Nov 2020 20:35:21 +0000

I made Kut to boost CLI productivity by organizing frequently used commands. I recently put lots of work into it and I am looking for testers / contributors / critiques!

Github: https://github.com/bettercallshao/kut

Kut reads from a repository of YAMLs of templated commands, and enables the user to render and execute the commands with arguments provided at run-time. It can help to

Avoid re-typing long commands over and over for routine tasks.
Version control and share commands.

Installation

Linux & Mac through Homebrew.

brew install bettercallshao/tap/kut

Windows through Scoop.

scoop bucket add bettercallshao https://github.com/bettercallshao/scoop-bucket
scoop install bettercallshao/kut

Or download latest zip from releases, extract, and put the binary files on your system path.

Quick start

Kick start by ingesting the demo menus.

kut i -s https://raw.githubusercontent.com/bettercallshao/kut-menus/master/python-demo.yaml
kut i -s https://raw.githubusercontent.com/bettercallshao/kut-menus/master/developer-demo.yaml

See a list of commands by running kut h.

NAME:
   kut - Run commands easily.

USAGE:
   kut [global options] command [command options] [arguments...]

VERSION:
   v0.5.2-20201123005537

COMMANDS:
   start, s           Starts executor for a menu
   ingest, i          Ingests menu locally from a source
   developer-demo, d  Developer commands for demo
   python-demo, p     Python commands for demo
   help, h            Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)

start, ingest, help, --help, --version are global arguments.
python-demo and developer-demo are command definitions.

Check what is in python-demo by kut p -h.

NAME:
   kut python-demo - Python commands for demo

USAGE:
   kut python-demo command [command options] [arguments...]

COMMANDS:
   uuid, u                 Generate a UUID
   forex-rate, f           Print forex rates
   mortgage-calculator, m  Calculate mortgage payment
   bit-expander, b         Convert between decimal, hex, and bit representations
   csv-to-markdown, c      Convert a CSV to markdown table
   help, h                 Shows a list of commands or help for one command

OPTIONS:
   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)

Check what forex-rate does with kut p f -h.

NAME:
   kut python-demo forex-rate - Print forex rates

USAGE:
   kut python-demo forex-rate [command options] [arguments...]

OPTIONS:
   --base value, -b value     Base currency (default: "USD")
   --symbols value, -s value  Comma separated currency symbol list (default: "CAD,GBP")
   --dry, -d                  render command but don't run (default: false)
   --help, -h                 show help (default: false)

--dry, --help are flags defined by kut.
--base, --symbols are input arguments, with default values.

Lets try EUR to JPY and AUD.

$ kut p f -b EUR -s JPY,AUD
On 2020-11-13
1 EUR can buy 123.88 JPY
1 EUR can buy 1.63 AUD

Use the --dry flag to see what actually ran.

$ kut p f -b EUR -s AUD -d
template: python3 -u -c "
import urllib.request
import urllib.parse
import json

url = 'https://api.exchangeratesapi.io/latest?base={{.base}}&symbols={{.symbols}}'
r = json.load(urllib.request.urlopen(url))

date = r['date']
rates = r['rates']

print(f'On {date}')
print('\n'.join(
  f'1 {{.base}} can buy {rates[symbol]:.2f} {symbol}'
  for symbol in rates
))
"

rendered: python3 -u -c "
import urllib.request
import urllib.parse
import json

url = 'https://api.exchangeratesapi.io/latest?base=EUR&symbols=AUD'
r = json.load(urllib.request.urlopen(url))

date = r['date']
rates = r['rates']

print(f'On {date}')
print('\n'.join(
  f'1 EUR can buy {rates[symbol]:.2f} {symbol}'
  for symbol in rates
))
"

First the command template was printed, then the command rendered with input arguments. The command is defined in $HOME/.kut/menus/python-demo.yaml.

name: python-demo
version: v0.1.0
help: Python commands for demo
actions:
- name: forex-rate
  help: Print forex rates
  template: |
    python3 -u -c "
    import urllib.request
    import urllib.parse
    import json

    url = 'https://api.exchangeratesapi.io/latest?base={{.base}}&symbols={{.symbols}}'
    r = json.load(urllib.request.urlopen(url))

    date = r['date']
    rates = r['rates']

    print(f'On {date}')
    print('\n'.join(
      f'1 {{.base}} can buy {rates[symbol]:.2f} {symbol}'
      for symbol in rates
    ))
    "
  params:
  - name: base
    help: Base currency
    value: USD
  - name: symbols
    help: Comma separated currency symbol list
    value: CAD,GBP

Add to this file or create more YAMLs in $HOME/.kut/menus/ to add more commands.

Web interface

Kut can also be run in conjunction with kutd to give a web based user interface to the menus. Kutd is installed as part of the kut package and runs without arguments.

[kutd] 2020/11/24 01:42:01 version: v0.5.2-20201123005537
[kutd] 2020/11/24 01:42:01 starting kutd ...
[kutd] 2020/11/24 01:42:01 listening on http://127.0.0.1:7171

It is recommended to install kutd as a start up service for convenience with the official helper menus.

For Windows (see help for more commands).

kut i -s https://raw.githubusercontent.com/bettercallshao/kut-menus/master/windows-kutd.yaml
kut windows-kutd startup-add

For Mac (see help for more commands).

kut i -s https://raw.githubusercontent.com/bettercallshao/kut-menus/master/mac-kutd.yaml
kut mac-kutd startup-add

Once kutd is running, visit http://127.0.0.1:7171 in browser to find three sections.

Channels - each channel is a placeholder for a kut executor to connect to. If visited without active connection, it shows a blank message.
Menus - each available menu can be viewed as a JSON.
Ingestion - ingesting menus same as kut.

As an example, we will run the csv-to-markdown command in the web interface. First open a terminal (with python3 available) and connect a kut executor to kutd (on channel 0 by default) declaring the python-demo menu.

kut s -m python-demo

Logs are printed and the command should block and occupy the terminal. Now visit channel 0 on the page, click on csv-to-markdown, copy the following into the data param, press execute, then toggle markdown to render it.

Name,Icon,Website
Facebook,[![Website shields.io](https://img.shields.io/website-up-down-green-red/http/shields.io.svg)](),https://facebook.com/
Twitter,[![Website shields.io](https://img.shields.io/website-up-down-green-red/http/shields.io.svg)](),https://twitter.com/home

Develop

To build, install golang and run make. The CI is powered by GoReleaser and CircleCI.

Further info

I wrote a blog series on kut https://bettercallshao.com/tags/kut/

Please contact me via https://bettercallshao.com/author/