Adrienne Tacke PRO
🇵🇭 Software Engineer & Sr. Developer 🥑 @ Cisco • Published Author • LinkedIn Learning Instructor • Twitch Streamer 🕹 Most important: I spend way too much money on desserts and endless hours playing Borderlands
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
@AdrienneTacke
The Bad
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!
