The document discusses three ways that developers can be lost or confused by documentation: 1) Developers may not be familiar with code conventions. 2) Setting up development environments can be difficult due to differences in operating systems and environments. 3) Developers lack context about what a product does without explanations or examples provided. It provides examples of each problem and recommends solutions like including a conventions legend, explaining commands for different shells, and adding introductory context to tutorials.

1. HOW TO LOSE A DEV IN
3 WAYS
jamie@mlh.io @SteministBarbie
By Jamie Wittenberg

2. 1 Introduction
2
3 What You Can Do Tomorrow
4 Questions
Three Ways to Lose A Dev
👉
What I'm Going to Share about Documentation 📚

3. Hey there, I’m
Jamie Wittenberg
I’m a Product Manager for

4. & formerly

5. Why You Should Listen to Me
& many more!

6. ● The end product should function as a tutorial to give users a working
introduction to using Python for AI purposes
● Users might not be able to install any software on their machines
● Users definitely don't have access to credit cards
● Users should not have to enter their email addresses or any personally
identifying information
● Users should be able to save their work and return to it (nice to have)
● The budget for the project was not large enough that I could have an
engineering team build out a browser-based sandbox (hey, a girl can dream)
● Some of the users will have not written a line of code before
● Some of them might be using tablets or cell phones for this introduction
The Project Had These Requirements 📝

8. Why does this matter?

9. 💯 The right thing to do.
💥 Your best marketing material.
🕘 Someone’s first experience with your product.
Inclusive Documentation Is . . .

10. Your Docs are Marketing Materials

11. 👉
1 Introduction
2
3 What You Can Do Tomorrow
4 Questions
Three Ways to Lose A Dev
What I'm Going to Share about Documentation 📚

12. Way #1

13. New devs aren't familiar with
code conventions.
WAY #1 😓

14. EXAMPLE I 👀

15. EXAMPLE I 👀

16. SOLUTION I 🙌
Include a legend in your documentation that defines any
conventions used.

17. EXAMPLE II 👀

18. SOLUTION II 🙌
Use visual differentiation to indicate different parts of the
developer workflow.

19. EXAMPLE III 👀

20. SOLUTION III 🙌
Include a screencast or gifs of someone following one of
your tutorials.

21. You might be losing devs by assuming
knowledge of conventions and
workflows.
TO RECAP ✅

22. TO RECAP ✅
Problem Solution
New developers aren't familiar with
conventions.
Add a legend to your
documentation.
New developers aren't familiar with
developer workflows, such as when
to use the command line vs a text
editor
Use visual differentiation
between different parts of the
workflow.
Even with the best explanations,
some things get lost.
Use screencasts or gifs.

23. Way #2

24. Development environments
are hard.
WAY 2 😓

25. EXAMPLE I 👀

26. SOLUTION IA 🙌
Link to someone else's explanation of how to use
different operating systems.

27. SOLUTION IB 🙌
Write up your own
detailed solution.

28. EXAMPLE II 👀

29. SOLUTION II 🙌
Explain commands and environment differences.

30. EXAMPLE III 👀

31. SOLUTION IIIA 🙌
Set up examples on CodePen, Glitch, or repl.it.

32. Offer a VPS/VM solution.
SOLUTION IIIB 🙌

33. You might be losing devs by not
accounting for differences in operating
systems and environments.
TO RECAP ✅

34. TO RECAP ✅
Problem Solution
Some packages behave differently
based on operating system.
Link to or create detailed
installation instructions for pre-
requisites by operating system.
Commands are not universal.
Account for different shells when
giving commands, and explain the
commands as you go.
Setting up development
environments can be tricky.
Use a browser-based IDE to host a
template, or describe how to use a
VPS/VM to try your product.

35. Way #3

36. New devs lack context.
WAY 3 😓

37. EXAMPLE I
👀

38. SOLUTION I
🙌
Add a few sentences at
the beginning of your
quickstarts and tutorials
to explain what they do.
Include key activities.

39. EXAMPLE II 👀

40. SOLUTION II 🙌
Provide use cases for your product and use them to guide
developers through your documentation.

41. EXAMPLE III 👀

42. EXAMPLE III 👀

43. SOLUTION III 🙌
Create a sandbox where developers can try a limited version
of your product.

44. You might be losing devs by not
providing context about your product
and documentation.
TO RECAP ✅

45. TO RECAP ✅
Problem Solution
New developers don't know what
your product does.
Add a few sentences at the
beginning of your quickstarts and
tutorials. Include key activities.
Your docs are expansive (which is
great!) and hard for a new dev to
navigate.
Provide use cases for your product
and use them to guide developers
through your documentation.
Your docs are hard to find or your
product requires sign up to test.
Create a sandbox.

46. Recap

47. New devs aren't familiar with code conventions.
Development environments are hard.
New devs lack context.
1
2
3
3 WAYS TO LOSE A DEV

48. 👉
1 Introduction
2
3 What You Can Do Tomorrow
4 Questions
Three Ways to Lose A Dev
What I'm Going to Share about Documentation 📚

49. ● Have a friend with less development experience try one
of your tutorials and document every confusing point
● Test your docs on different operating systems.
● Create a legend for your documentation.
● Add a glossary to your documentation.
● Add context to your tutorials.
What You Can Do Tomorrow 🗓

50. 👉
1 Introduction
2
3 What You Can Do Tomorrow
4 Questions
Three Ways to Lose A Dev
What I'm Going to Share about Documentation 📚

51. I would love to answer your
questions!
https://mlhlocal.host/devrelcon

52. Thanks, I’m
Jamie Wittenberg
mlhlocal.host/devrelcon
jamie@mlh.io @SteministBarbie