The Art Of Documentation. Delivered at NDC Porto 2022 on 27/04/2022

1. THE ART OF
DOCUMENTATION AND
THE README.md
@Ben_Hall
Ben@BenHall.me.uk
O’Reilly Media

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 / Ben@BenHall.me.uk
Founder of Katacoda.com
Acquired by O’Reilly Media in November
2019
WHO
AM
I?

4. Learn via Interactive Browser-Based Labs

6. Agenda?
1. User’s journey with Open Source
Projects
2. Documentation required to support
Users
3. Examples/Inspiration of documentation

9. Documentation
Potential Users
Implementers
Contributors
Maintainers

10. Documentation
Potential Users
Implementers
Contributors
Maintainers

11. Documentation
Potential Users
Implementers
Contributors
Maintainers

12. Documentation
Potential Users
Implementers
Contributors
Maintainers

13. Documentation
Potential Users
Implementers
Contributors
Maintainers

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

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

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

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

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

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

22. 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.

23. "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

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

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

27. Think of target audience
Remember Janet!

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

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

30. “Download 10GB VM”

31. “Just deploy using
Cloud Formation”

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

33. Short Videos / Gifs

34. Examples!

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

42. Competitive Advantage

43. Help users get started
with examples!
Let them explore and experiment!

45. Be careful of
assuming
prior knowledge

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

50. Not everyone’s first language is English

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

52. https://alexjs.com/
Catch insensitive, inconsiderate writing

53. $ alex example.md
example.md
1:5-1:14 warning `boogeyman` may be insensitive, use `boogey` instead boogeyman-boogeywoman
1:42-1:48 warning `master` / `slaves` may be insensitive, use `primary` / `replica`
instead master-slave
2:52-2:54 warning `he` may be insensitive, use `they`, `it` instead he-she
2:61-2:68 warning `cripple` may be insensitive, use `person with a limp` instead cripple
⚠ 4 warnings

54. https://github.com/theashraf/alex-action

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

56. Documentation
Requirements Change

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

58. 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

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

65. Remember the
user’s emotions
at this point

66. StackOverflow?
Github Issues?

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

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

70. Community and
Contributor guidelines

71. Mozilla Wrangling Web Contributions:
How to Build a CONTRIBUTING.md
• Welcome
• Table of Contents:
• Short Links to Important
Resources:
• docs
• bugs
• comms
• Testing
• How to submit changes
• How to report a bug
• Templates
• First bugs for
Contributors
• How to request an
"enhancement"
• Style Guide / Coding
conventions
• Code of Conduct
• Recognition model
• Who is involved?
• Where can I ask for help?

72. Code of Conduct

73. License

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 🙌

89. Real World Examples
What difference does it make?

100. This is where you
can have a huge
Impact on OSS!

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

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

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

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

110. Thank you!
This was “The Art of Documentation”
@Ben_Hall
Ben@BenHall.me.uk

111. Thank you!
This was “The Art of Documentation”
@Ben_Hall
Ben@BenHall.me.uk
Simpsons s19e01