Technical Writer

• Author (RHCE)

• Linux Annoyances for Geeks

• Linux user since 1999

• Principal Technical Writer, NGINX (F5)

CC0

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

@mjang.bsky.social

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

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)

Text Can't Solve

Bad Design

• Close
• Open
• Lock
• Instructions?

Credit:  Beth Aitman

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

-

-

Text

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)

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