I want you to think of

@AdrienneTacke

some tutorial,

a technical guide,

documentation, or

you've used...

any learning resource

'Think of the                                                   ${learningResource}

you've used...'

best

worst

@AdrienneTacke

Documentation: The       Pieces

Missing

@AdrienneTacke

The Bad

@AdrienneTacke

The Bad
Jack Skellington looking confused saying "What does it mean?"

@AdrienneTacke

The Bad
Jack Skellington looking confused saying "What does it mean?"
Most "bad" learning resources are       and

unclear

unusable

@AdrienneTacke

The Bad

unclear

unusable

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
SMH, IDK
To create a TTL index on this field, use the following command.
"
The CRI is an API for container runtimes to integrate with kubelet on a node.
Whether you're using the MERN, MEAN, or MEVN stack, this tutorial will be useful to learn the fundamentals.

@AdrienneTacke

The Bad
SMH, IDK
Time-to-live
Container Runtime Interface 
Application Programming Interface
MongoDB Express React Node
MongoDB Express Angular Node
MongoDB Express Vue Node
TTL
CRI API
MERN MEAN MEVN

@AdrienneTacke

The Bad
SMH, IDK
Time-to-live
Container Runtime Interface 
Application Programming Interface
MongoDB Express React Node
MongoDB Express Angular Node
MongoDB Express Vue NodeDB
TTL
CRI API
MERN MEAN MEVN

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
Step skipper
1. Create this thing
2. Add this code
3. Tada! You should be up and running now!

@AdrienneTacke

Source: Jombo (YouTube)
The Bad
Step skipper
1. Create this thing.
2. Add this code.
3. Tada! You should be up and running now!

@AdrienneTacke

The Bad
Step skipper
1. Create this thing.
2. Add this code.
2a. Replace placeholders with your own values.
1a. Set this setting, if not on by default.
2b. Don't forget to hit the "Deploy" button!
3. Tada! You should be up and running now!

@AdrienneTacke

💡 Protip: Be sure to delete this thing when finished, otherwise you may incur costs!
The Bad
Step skipper
1. Create this thing.
2. Add this code.
2a. Replace placeholders with your own values.
1a. Set this setting, if not on by default.
2b. Don't forget to hit the "Deploy" button!
3. Tada! You should be up and running now!

@AdrienneTacke

💡 Protip: Be sure to delete this thing when finished, otherwise you may incur costs!
The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
foo your foobar

@AdrienneTacke

const one = (a) => {
  let n = a
    .split('\n')
    .map(x => parseInt(x));

  for (let i = 0; i <= n.length; i++) {
    let foo = 2020 - n[i];
    let bar = n.filter(x => x == foo);

    if (n.filter(x => x == foo).length == 1) {
      return n[i] * bar;
    }
  }
}
The Bad
foo your foobar

@AdrienneTacke

const findProductOfTwoEntriesWhoseSumIs2020 = (input) => {
  let numbers = input
    .split('\n')
    .map(x => parseInt(x));
    
  for (let i = 0; i <= numbers.length; i++) {
    const partOneOf2020 = 2020 - numbers[i];
    const partTwoOf2020 = numbers.filter(x => x == partOneOf2020);

    if (numbers.filter(x => x == partOneOf2020).length == 1) {
      return numbers[i] * partTwoOf2020;
    }
  }
}

👋 German Naming Convention

The Bad
foo your foobar

@AdrienneTacke

const findProductOfTwoEntriesWhoseSumIs2020 = (input) => {
  let numbers = input
    .split('\n')
    .map(x => parseInt(x));
    
  for (let i = 0; i <= numbers.length; i++) {
    const partOneOf2020 = 2020 - numbers[i];
    const partTwoOf2020 = numbers.filter(x => x == partOneOf2020);

    if (numbers.filter(x => x == partOneOf2020).length == 1) {
      return numbers[i] * partTwoOf2020;
    }
  }
}

👋 German Naming Convention

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
Tell me what I need! 

what background knowledge will be helpful before starting this tutorial

Tell me:

@AdrienneTacke

The Bad
Tell me what I need! 

what background knowledge will be helpful before starting this tutorial

Prerequisites

@AdrienneTacke

The Bad
Tell me what I need! 

what dependencies do I need to download

Tell me:

@AdrienneTacke

The Bad
Tell me what I need! 

what dependencies do I need to download

what background knowledge will be helpful before starting this tutorial

Prerequisites

Dependencies

@AdrienneTacke

The Bad
Tell me what I need! 

Tell me:

if I can complete this on a free tier

@AdrienneTacke

The Bad
Tell me what I need! 

if I can complete this on a free tier

what dependencies do I need to download

what background knowledge will be helpful before starting this tutorial

Prerequisites

Dependencies

Potential Costs

@AdrienneTacke

The Bad
Tell me what I need! 

Tell me:

if some steps need to be completed before I start

@AdrienneTacke

The Bad
Tell me what I need! 

if some steps need to be completed before I start

if I can complete this on a free tier

what dependencies do I need to download

what background knowledge will be helpful before starting this tutorial

Prerequisites

Dependencies

Potential Costs

Preconditions

@AdrienneTacke

The Bad
Tell me what I need! 

Tell me:

an estimate of how long this should take

@AdrienneTacke

The Bad
Tell me what I need! 

an estimate of how long this should take

if some steps need to be completed before I start

if I can complete this on a free tier

what dependencies do I need to download

what background knowledge will be helpful before starting this tutorial

Prerequisites

Dependencies

Potential Costs

Preconditions

Time

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
Random screenshot, who dis?

Doesn't support what you're trying to explain

Paired with the incorrect step

Shows a different result than the one you describe

Alt text does not provide meaningful detail, or worse, is not used.

@AdrienneTacke

The Bad
Random screenshot, who dis?

Only add for additional clarity

Due diligence! Try naming your screenshots to match their step number.

Follow your own steps and recapture the actual results, if necessary.

At a minimum, describe the relevant settings/inputs/buttons needed to complete the step

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
Oh, you didn't know that?
Assume your reader has knowledge on the topic.

@AdrienneTacke

The Bad
Oh, you didn't know that?
Assume your reader has no knowledge on the topic.

@AdrienneTacke

The Bad
Oh, you didn't know that?
Assume your reader has no knowledge on the topic.

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
No more 404s
In this tutorial, you'll learn how to use fancy new technology through a variety of use cases. 

If you don't already have a fancyService account, be sure to create one before following this tutorial. Detailed instructions on setting up your account can be found here.

@AdrienneTacke

The Bad
No more 404s
In this tutorial, you'll learn how to use fancy new technology through a variety of use cases. 

If you don't already have a fancyService account, be sure to create one before following this tutorial. Detailed instructions on setting up your account can be found here.

@AdrienneTacke

The Bad
No more 404s
In this tutorial, you'll learn how to use fancy new technology through a variety of use cases. 

If you don't already have a fancyService account, be sure to create one before following this tutorial. Detailed instructions on setting up your account can be found here.

@AdrienneTacke

The Bad
No more 404s
In this tutorial, you'll learn how to use fancy new technology through a variety of use cases. 

If you don't already have a fancyService account, be sure to create one before following this tutorial. Detailed instructions on setting up your account can be found here.

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
Jump to recipe ⬇
The Bad
Jump to recipe ⬇
The Bad
Jump to recipe ⬇

@AdrienneTacke

The Bad
Jump to recipe ⬇

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
Not now, GIPHY

@AdrienneTacke

The Bad
Not now, GIPHY

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

The Bad
It works on my machine
"Sorry, this tutorial only works with Windows."
"This sample repo relies on version 3.2.6 and above."
"The rest of this guide assumes you have this SDK installed."

@AdrienneTacke

The Bad
It works on my machine
"Sorry, this tutorial only works with Windows."
"This sample repo relies on version 3.2.6 and above."
"The rest of this guide assumes you have this SDK installed."

@AdrienneTacke

The Bad
It works on my machine

Make it platform agnostic!

@AdrienneTacke

The Bad
It works on my machine

@AdrienneTacke

The Bad
It works on my machine

@AdrienneTacke

Prepare a template repo/starter app!

The Bad
It works on my machine

@AdrienneTacke

The Bad
It works on my machine

@AdrienneTacke

The Bad

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

@AdrienneTacke

unclear

unhelpful

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
SMH, IDK
Random screenshot, who dis?

concise

valuable

The Bare Minimum

@AdrienneTacke

Step skipper
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
Spell out abbreviations
Random screenshot, who dis?

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
Tell me what I need! 
foo your foobar
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
Spell out abbreviations
Random screenshot, who dis?

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
Tell me what I need! 
Use the German Naming Convention
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
Spell out abbreviations
Random screenshot, who dis?

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
Spell out abbreviations
Random screenshot, who dis?

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
No more 404s
Oh, you didn't know that?
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
Spell out abbreviations
Make screenshots make sense

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
No more 404s
Make sure they know that!
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
Spell out abbreviations
Make screenshots make sense

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
Repair those links
Make sure they know that!
Not now, GIPHY
It works on my machine
Jump to recipe ⬇
Spell out abbreviations
Make screenshots make sense

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
Repair those links
Make sure they know that!
Not now, GIPHY
It works on my machine
Add Quick Jump links and get on with your day
Spell out abbreviations
Make screenshots make sense

concise

valuable

The Bare Minimum

@AdrienneTacke

Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
Repair those links
Make sure they know that!
Just a little GIPHY for a snack, not to distract
It works on my machine
Add Quick Jump links and get on with your day
Spell out abbreviations
Make screenshots make sense

concise

valuable

The Bare Minimum

@AdrienneTacke

The Bare Minimum
Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
Repair those links
Make sure they know that!
Just a little GIPHY for a snack, not to distract
It works on all machines!
Add Quick Jump links and get on with your day
Spell out abbreviations
Make screenshots make sense

concise

valuable

@AdrienneTacke

Documentation: 
The
Check your steps, before ya wreck ya selves!
First things, first
Use the German Naming Convention
Repair those links
Make sure they know that!
Just a little GIPHY for a snack, not to distract
It works on all machines!
Add Quick Jump links and get on with your day
Spell out abbreviations
Make screenshots make sense

BEST PIECES

@AdrienneTacke

@AdrienneTacke

Salamat!

Adrienne Braganza Tacke
Cloud Developer Advocate @
📢 Announcement Soon!

Learned something?

Enjoyed my talk?

I'd love a tweet about it!

More questions? Find me afterward for Q&A!
 

Documentation: The Missing Pieces

By Adrienne Tacke

Documentation: The Missing Pieces

Most documentation, technical tutorials, and quick demos are written in a certain way. But for the true beginners, the career-transitioners, or those crossing domains? That technical content is certainly not written for them! Funnily enough, these same shortcomings affect “technical” people too, especially when it comes to learning something new. In this talk, I’d like to explore the ways we can make our documentation better by considering more kinds of people. We’ll discover common oversights and assumptions most documentation has built-in by default and learn how to fix them. We’ll also strengthen our technical writing skills to ensure, to the best of our ability, that every anticipated reader of our documentation never feels lost or frustrated. By the end of this talk, you’ll leave and never write documentation in the same way again…and that’s a good thing!

  • 605