Content

Design

Credit:  Torrey Podmajersky

Lessons

• Make Every Word Earn Its Place

Principal Technical Writer

Product Documentation

Mission

• Complete accurate documentation ...

Pixabay CC0

Background

Audience

• Writers
  • ​Content Designers
• UI Designers
• UI Developers
• Testers
• PMs
• Support and Sales
• Others

@TheMikeJang

Pixabay CC0

Content Design

We help users make decisions

https://slides.com/mike-1/ai-the-docs

We want to "unblock" users

Our style guides supply criteria

If AI were a teenager

• Teenagers

Mindset for AI

Make AI work for you

• AI answers the prompt

Manage those interns

Example:

What happens when you tell a teenager to wash the dishes

https://slides.com/mike-1/ai-the-docs

Fantasy Football

Fantasy Football

Fantasy Football

No "right" answers 

Choices. Depends on situation.

Fantasy Football

Fantasy football choices

https://slides.com/mike-1/ai-the-docs

Who should I start?

Better answer: it depends

Chance for progressive disclosure

If the design is already crowded

Minor detail for edge cases

Three tier model

Link to docs

How AI can help with content design

1.  Start with a style guide
2.  Set up instructions
3.  Build an AI Model
4.  Pull content from the style guide
5.  Organize the knowledge in AI
6.  Test the steps locally
7.  Identify problems
8.  Update the style guide
9.  Automate updates

Start with a Style Guide

• Designed for humans
• Content design skills for AI

Skills

• Well, sort of

• Well, sort of

• a reusable capability that can be invoked to perform a particular kind of task

Risks

• Why does AI hal
• Use distinct topics

Make it "easy" for ourselves

1.  Know your product
2. Set up instructions
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)

-

-

-

-

-

-

-

-

-

-

-

-

AI models -- Best practices

• Governing instructions
• Details in separate files
• Markdown

Make it "easy" for ourselves

• instructions.md

What we've done

• 30 different distinct pages

Instructions

“Quote or citation”

Instructions for AI

• Describe use cases

OMG AI

1.  Know your product
2. "Don't Make Me Think"
3.  Build a model
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)

-

-

-

-

-

-

-

-

-

-

-

Instructions & Skills

Organize for AI

Pixabay CC0

Is

This

Zen?

Format for AI

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Pull content from your style guide

-

-

-

-

-

-

-

-

-

Convert your style guide

• Format only

• Emerging standard for AI: Markdown

Conversion

HTML to Markdown

Writing for AI

1.  Know your product
2. "Don't Make Me Think"
3.  One easy breath
4.  Two thoughts
5.  Organize the knowledge for AI

-

-

-

-

-

-

-

-

-

-

Structure your instructions

• Straightforward set of steps

• Reference to a directory of "skills"

Before you deploy

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

-

-

-

-

-

-

-

-

-

-

Tip: pinned instructions

Work "locally"

Avoid "hallucinations"

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.  Test edge cases

-

-

-

-

-

-

-

-

-

The Challenge

Know Your Stakeholders

Test and Iterate

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.  Share your work

-

-

-

-

-

-

-

"Easy Stuff"

• Functional Text

• Capitalization

• Grammar

Examples of Bad UI Text

• Billboards
• Street Signs
• Airplanes
• UIs

 Fair use (I hope)

UI Text Can't Solve

Bad Design

• Close
• Open
• Lock
• Instructions?

Credit:  Beth Aitman

What Floor?

Source: Quora

Bad UI
Text

Extracted?

Text

Credit:  Ryan Bigge

Useless UI Text

@TheMikeJang

Credit: Gordon Hatton CC-SA-2.0

Worst UI Text Ever

(IMO)

@TheMikeJang

Worst

UI Text

Source: Hawaii Emergency Management Agency

@

Result:

Panic!

Better UI Text