Delivered at Kubecon US 2018 by Ben Hall. Watch the recording at https://www.youtube.com/embed/Yjxupg-NKnA In this talk, Ben uses his expertise of building an Interactive Learning Platform to highlight The Art of Documentation. The aim of the talk is to help open source contributors understand how small changes to their documentation approach can have an enormous impact on how users get started.

1. THE ART OF
DOCUMENTATION
@Ben_Hall
Ben@Katacoda.com
Katacoda.com

2. The Open Source Survey is an open data project
by GitHub and collaborators from
academia, industry, and the broader open source community

3. @Ben_Hall / Blog.BenHall.me.uk
Microsoft MVP – Cloud and Datacenter
Management
Founder of Katacoda.com
WHOAMI?

4. Learn via Interactive Browser-Based Labs
Katacoda.com

5. Learn.OpenShift.com

7. envoyproxy.io/try

8. Agenda?
1. Users journey with Open Source
Projects
2. Documentation to support Users
3. Examples/Inspiration of
documentation

11. Documentation
Potential Users
Implementers
Contributors
Maintainers

12. Documentation
Potential Users
Implementers
Contributors
Maintainers

13. Documentation
Potential Users
Implementers
Contributors
Maintainers

14. Documentation
Potential Users
Implementers
Contributors
Maintainers

15. Documentation
Potential Users
Implementers
Contributors
Maintainers

17. Janet has joined a new team! New ideas, new concepts.
New open source projects
Potential New User

18. No-One Reads
No-One Writes
Everyone Wants Docs

19. https://www.nngroup.com/articles/f-shaped-pattern-reading-
web-content/

21. Reading Large Blocks
Of Text is difficult
Writing Large Blocks
Of Text is painful

22. Commitment pattern (rare)
Consists of fixating on almost everything on the
page.

23. Layer-cake pattern
Occurs when the eyes scan headings and
subheadings and skip the normal text below

24. Spotted pattern
Consists of skipping big chunks of text and scanning
as if looking for something specific, such as
a link, digits, a particular word.

25. "It deosn't mttaer in waht oredr the ltteers in a wrod
are, the olny iprmoetnt tihng is taht the frist and lsat
ltteer be at the rghit pclae. The rset can be a toatl
mses and you can sitll raed it wouthit porbelm. Tihs
is bcuseae the huamn mnid deos not raed ervey
lteter by istlef, but the wrod as a wlohe."
https://www.mnn.com/lifestyle/arts-culture/stories/why-your-
brain-can-read-jumbled-letters

26. https://www.quora.com/Why-do-I-see-words-that-arent-there-
when-I-am-reading

27. https://www.quora.com/Why-do-I-see-words-that-arent-there-
when-I-am-reading

29. Think of target audience
Remember Janet!

30. Does this project
solve my problem?
Will the project help
my career?

31. Readme.md will likely be the
first experience for many
users

32. “Download 10GB VM”

33. “Just deploy using
Cloud Formation”

34. Aim:
How can you showcase the
value without large
commitment from the user?

35. Short Videos / Gifs

36. Examples!

43. Empower people to feel
confident and build trust
Isn’t this fundamentally the aim of documentation?

44. Competitive Advantage

46. Be careful of
assuming
prior knowledge

50. https://beta.developer.spotify.com/documentation/web-playback-sdk/quick-start/#initializing-the-sdk

51. Not everyone’s first language is English

52. Inclusive Languages
“Just”, “Easy”, “Simple”, “Anyone can do it!”
“He”, “Him”
😡

53. Janet loves your project! It solves their problems!
Active User!

54. Documentation
Requirements Change

55. 1| SOLVE MY OTHER
PROBLEMS 🤔
2| OH NO! IT’S BROKEN 🔥

56. What else is possible?
Asking questions about implementation
How do I solve particular problems?
Very similar to exploration
when getting started.
Can assume prior knowledge

63. 🙀🔥😿
Something has gone wrong!
What documentation do you need when everything is on fire?

64. Remember the
user’s emotions
at this point

65. StackOverflow?
Github Issues?

66. The best documentation is
the one you don’t have to
write

68. The 🔥 is out
Janet has new experiences
to share
Potential New Contributor 🙌

69. Community and
Contributor guidelines

70. Code of Conduct

71. License

81. https://github.com/katacoda-scenarios/

83. Longer form content!
Design Docs, Reference API

85. Janet has made a impact
to the community.
Ready to become a
maintainer!
Potential New Maintainer 🙌

98. WHAT IS THE ART OF
DOCUMENTATION??
3 key points

99. 1| Developers Experiment 🐶
Your documentation should
support this mindset

100. 2| Users get into trouble 🔥
Where might users become
struck?

101. 3| Encourage Contributors 🙌
Everyone has a story to tell.