Technical Writer

• Author (RHCE)

• Linux Annoyances for Geeks

• Linux user since 1999

• Principal Technical Writer, NGINX (F5)

CC0

@theMikeJang

https://slides.com/mike-1/open-source-and-docs

Background

Inspiration

First love: CLI

Command line interface guidelines

https://clig.dev

The original UNIX shell

The CLI Today

Get help at the CLI

Preferred User Experience

Kernel Panic

Text

Kernel Panic

Target Persona

People who know the command line interface

User preferences

User preferences

Observability

Exceptions

Security

Why people don't trust help text

 Fair use (I hope)

Better content at the CLI

1.  Know your product
2. "Don't Make Me Think"
3.  Organized and Scannable
4.  Organized options
5.  Minimize need for docs
6.  Know your stakeholders
7.  Start with the easy stuff
8.  Harder stuff: do your homework
9.  Scaling: use style guides

Know Your Product

• Complete, Accurate Depiction of Functionality

From the help text

Help Users Do Their Jobs

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Two thoughts
5.  Minimize need for docs
6.  Know your audience
7.  Know your stakeholders
8.  Start with the easy stuff
9.  Harder stuff: do your homework
10.  Use style guides (details)

-

-

-

-

-

-

-

-

-

-

-

-

1.  Know your product
2. "Don't Make Me Think"
3.  Organized and Scannable
4.  Organized options
5.  Minimize need for docs
6.  Know your audience
7.  Know your stakeholders
8.  Start with the easy stuff
9.  Harder stuff: do your homework
10.  Scaling: use style guides

-

-

-

-

-

-

-

-

-

-

Better content at the CLI

Principles

of Content Design

Credit:  Steve Krug

Organization is Zen

1.  Know your product
2. "Don't Make Me Think"
3.   Organized and Scannable Two thoughts
4.  Minimize need for docs
5.  Know your audience
6.  Know your stakeholders
7.  Start with the easy stuff
8.  Harder stuff: do your homework
9.  Use style guides (details)

-

-

-

-

-

-

-

-

-

-

-

One Easy Glance

Organized is Zen

Pixabay CC0

Is

This

Zen?

Option

Cause and Effect

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Organized options
5.  Minimize need for docs
6.  Know your audience
7.  Know your stakeholders
8.  Start with the easy stuff
9.  Harder stuff: do your homework
10.  Use style guides (details)

-

-

-

-

-

-

-

-

-

Organized Help

Option

Simplicity -> Docs

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Two thoughts
5.  Minimize need for docs
6.  Know your audience
7.  Know your stakeholders
8.  Start with the easy stuff
9.  Harder stuff: do your homework
10.  Use style guides (details)

-

-

-

-

-

-

-

-

-

-

The Stakeholder Challenge

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Two thoughts
5.  Minimize need for docs
6.  Know your stakeholders
7.  Start with the easy stuff
8.  Harder stuff: do your homework
9.  Use style guides (details)

-

-

-

-

-

-

-

-

-

The Challenge

Know Your Stakeholders

Stakeholders

• Product Managers
• Back-end Developers
• Support and Sales
• Testers (QA)
• Writers

Product Manager

• Sales
• Customers
• Bandwidth

Pixabay CC0

Backend

Developers

CLIs are

Under the Hood

Pixabay CC0

Support and Sales

• Customers ask you first

• You have customer perspective

Pixabay CC0

Tester

• UI Text: measurable

• QA == Your Friend

Pixabay CC0

Writer

• Structure is everything

• Tolkien, not Keroac

Implementation

Pixabay CC0

Humans first

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Two thoughts
5.  Minimize need for docs
6.  Know your stakeholders
7.  Remember the machines
8.  Harder stuff: do your homework
9.  Use style guides (details)

-

-

-

-

-

-

A human-friendly CLI

• Humans

• Machines (scripts)

CLI for humans

• Output that makes sense

Be Flexible

• Minimal viable text
• Incomplete sentences OK
• No periods OK (single sentence)
• Incorrect grammar OK (if it works)
• Don't apologize, don't say please (unless necessary)

When to say please

• Error messages
• Whenever something is not the user's fault
• Whenever a user thinks they "did it right"

Don't Be This Guy

Better Text Requires Homework

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Two thoughts
5.  Minimize need for docs
6.  Know your stakeholders
7.  Start with the easy stuff
8.  Harder stuff: structure your help
9.  Use style guides (details)

-

-

-

-

-

-

Simple parts - working together

• Structure your commands

• Organize your options

Saying just enough

• A balance

• Reassure your users

• Don't overwhelm

Audiences

• People who are learning

• People who follow "patterns"

• Don't overwhelm

People who are learning

• Need "more" help

• Don't overwhelm

People who follow patterns

• Want "just" the examples

• Don't overwhelm

Replicating Simplicity

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Two thoughts
5.  Minimize need for docs
6.  Know your stakeholders
7.  Start with the easy stuff
8.  Harder stuff: do your homework
9.  Scaling: established guides

-

-

-

-

-

Use clig.dev

• Concise help by default

• More help when asked (--help)

Concise help by default

• Description

• Example commands 

• Description

• Essential flags 

• Suggest --help for more info

Can you use AI

• Maybe not even necessary

• Try the BethBot

• Strate

Feed a style guide

• Audience, reading level

• Voice

• Common terms

• Limits (text length)