The document provides insights on effective documentation practices, emphasizing the importance of clarity, structure, and user-centric design. It discusses how people read documents, recommending key strategies like using prominent headers, maintaining focused paragraphs, and integrating user-friendly error messages. Additionally, it outlines the significance of contributing to documentation and fostering a community that values collaborative improvement.

1. THINGS I WISH PEOPLE TOLD
ME ABOUT WRITING DOCS
@taylor_atx

2. Community Engineer at Keen IO
taylor@keen.io
@taylor_atx
TAYLOR BARNETT

3. HOW DO PEOPLE
ACTUALLY READ DOCS?
@taylor_atx

4. @taylor_atx

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

6. IMPLICATIONS OF F SHAPE
• First two paragraphs must state the most important
information
• Further, the first 3-5 words are very important
• Start headers, paragraphs, and bullet points with information-
carrying words
• Variations in typeface (text size, links, bold, etc)
@taylor_atx

7. STRUCTURE
• Prevent search failure - what the users wants doesn’t stand
out
• One idea per paragraph, if there’s more than one, split the
paragraphs
• Users skip over things that look like ads
• Aim for 65-90 characters in width
@taylor_atx

8. USABILITY VARIES: PARAGRAPH VS BULLETS
@taylor_atx

9. USABILITY VARIES: PARAGRAPH VS BULLETS
Event collections can have
almost any name, but there
are a few rules to follow: The
name must be 64 characters
or less. It must contain only
Ascii characters. It cannot be
a null value.
@taylor_atx

10. USABILITY VARIES: PARAGRAPH VS BULLETS
Event collections can have
almost any name, but there
are a few rules to follow: The
name must be 64 characters
or less. It must contain only
Ascii characters. It cannot be
a null value.
Event collections can have
almost any name, but there
are a few rules to follow:
• The name must be 64
characters or less.
• It must contain only Ascii
characters.
• It cannot be a null value.
@taylor_atx

11. USERS ACTUALLY READ
CODE SNIPPETS
@taylor_atx

12. var client = new Keen({
projectId: "your_project_id",
writeKey: "your_write_key"
});
var ticketPurchase = {
price: 50.00,
user: {
id: "020939382",
age: 28
},
artist: {
id: "19039",
name: "Tycho"
}
}
client.addEvent("ticket_purchases", ticketPurchase);
WHAT IS THIS CODE SNIPPET MISSING?
🤔
@taylor_atx

13. var client = new Keen({
projectId: "your_project_id",
writeKey: "your_write_key"
});
var ticketPurchase = {
price: 50.00,
user: {
id: "020939382",
age: 28
},
artist: {
id: "19039",
name: "Tycho"
}
}
client.addEvent("ticket_purchases", ticketPurchase);
WHAT IS THIS CODE SNIPPET MISSING?
• First, how do I even run this?
"
@taylor_atx

14. var client = new Keen({
projectId: "your_project_id",
writeKey: "your_write_key"
});
var ticketPurchase = {
price: 50.00,
user: {
id: "020939382",
age: 28
},
artist: {
id: "19039",
name: "Tycho"
}
}
client.addEvent("ticket_purchases", ticketPurchase);
WHAT IS THIS CODE SNIPPET MISSING?
• First, how do I even run this?
• “ReferenceError: Keen is not defined”
"
@taylor_atx

15. var client = new Keen({
projectId: "your_project_id",
writeKey: "your_write_key"
});
var ticketPurchase = {
price: 50.00,
user: {
id: "020939382",
age: 28
},
artist: {
id: "19039",
name: "Tycho"
}
}
client.addEvent("ticket_purchases", ticketPurchase);
WHAT IS THIS CODE SNIPPET MISSING?
• First, how do I even run this?
• “ReferenceError: Keen is not defined”
• Didn’t set the Project ID and Write Key
"
@taylor_atx

16. What will this return?
# Copy and paste the following command
$ gem install rails
PREVENT COPY AND PASTE BUGS
🤔
@taylor_atx

17. What will this return?
# Copy and paste the following command
$ gem install rails
PREVENT COPY AND PASTE BUGS
😔
# Returns “bash: command not found: $”
@taylor_atx

18. TWILIO
@taylor_atx

19. WHAT DO I MEAN BY “DOCS?”
API REFERENCES
GUIDES
TUTORIALS
BLOG POSTS*
@taylor_atx

20. GUIDES
• Somewhere between API references and tutorials
• Similar reference but with prose that explains how to use the
API
• Example: Authorization guide
@taylor_atx

22. TUTORIALS
• Teach specific things with an API, beginning to end, including
setup
• Tightly focused on a few pieces of functionality
• Includes working sample code
• Example: Getting Started or Hello World tutorial
@taylor_atx

23. SPRING FRAMEWORK
@taylor_atx

24. BLOG POSTS
• “Share Knowledge, Not Features” — Adam DuVander
• Features != Benefits
• A blog post should teach, inspire, and help
• Give a preview, then help navigate them to the full docs
@taylor_atx

25. @taylor_atx

26. DOCS NAVIGATION AND
UNIVERSAL PRINCIPLES OF
DESIGN
@taylor_atx

27. 1. PROGRESSIVE
DISCLOSURE
@taylor_atx

28. 1. NAVIGATE FROM DOC
SET TO DOC SET
@taylor_atx

29. DOCS PORTAL HOMEPAGE
PRODUCT HOMEPAGE
SECTION HOMEPAGE
PAGE
@taylor_atx

30. @taylor_atx

31. 2. IMMERSION
@taylor_atx

32. 2. ALLOW NAVIGATION
WITHIN CONTENT
@taylor_atx

33. BOTTOM-UP NAVIGATION
• If you tell me I can do something, link to how to do that
something.
• If you tell me I can use something, link to a description of
that something.
• If you mention a concept or an idea, link to a description of
that concept or idea.
— Mark Baker from “Every Page is Page One”
@taylor_atx

34. @taylor_atx

35. 3. MODULARITY
@taylor_atx

36. 3. REDUCE INFORMATION
FRAGMENTATION
@taylor_atx

37. @taylor_atx

39. 😨
😨
@taylor_atx

40. LIBRARIES
SDKS
WRAPPERS
CLIENTS
@taylor_atx

41. WHY DO BAD NAMES PERSIST?
• Because we don’t realize that the name is bad
• Or we do, but can’t or won’t justify fixing it because we…
• Are tied to it
• Can’t justify the time
• Don’t know the value
• Don’t have the agency to fix it
@taylor_atx

42. EMPATHY FAILURE
BEGINNER’S MIND FAILURE
@taylor_atx

43. WORD CHOICE IS HARD
• Hard to give one framework to use, but you can…
• Talk to users, get feedback - ask someone to review it
• Refactor and rewrite
• Search existing names
@taylor_atx

44. @taylor_atx

45. ERROR MESSAGES
@taylor_atx

46. ERROR MESSAGES
ARE AN OPPORTUNITY
@taylor_atx

47. 3 H’S OF GOOD ERROR MESSAGES:
HUMBLE
HUMAN
HELPFUL
@taylor_atx

48. HUMBLE
• Apologize even if it is not your fault
• Example:
• Sorry, we could not connect to ___. Please check your
network settings, connect to an available network, and try
again.
@taylor_atx

49. HUMAN
• Speak in human terms
• Example:
• Your API Key is invalid, please try a different key.
@taylor_atx

50. HELPFUL
• Share what the users can expect or do to fix the problem
• Example:
• Sorry, the image you tried to upload is too big. Try again
with an image smaller than 4000px tall by 4000px wide.
@taylor_atx

51. WRITING ERROR MESSAGES
1. Acknowledge
2. Apologize
3. Explain
4. Help
@taylor_atx

52. WRITING ERROR MESSAGES
• Object first, action second
• What the users wants first, how to get there second
• If you can, put the input in the error string
@taylor_atx

53. ERROR MESSAGE SEO
• If users get an error message often, put the exact text in your
docs
• You can also edit StackOverflow posts
@taylor_atx

54. HOW DO I GET OTHER
TEAMMATES TO CONTRIBUTE
TO DOCS?
@taylor_atx

55. “I DON’T HAVE THE TIME”
“DOCS ARE HARD TO MAINTAIN”
“JUST READ THE SOURCE”
“DOCUMENTATION IS USELESS”
— Fred Hebert from “Don't be a Jerk: Write Documentation”
@taylor_atx

56. MAKE SURE CONTRIBUTORS
ARE VALUED & REWARDED
@taylor_atx

57. SHOW THE BENEFITS
@taylor_atx

58. GITHUB FOR DOCS
• Continuous integration and automated testing
• Issues
• Incremental changes
@taylor_atx

59. REVIEWS
• “Pair” on reviews
• Use reviews to coach contributors
• For small suggestions, fix it yourself and share before
merging
• If a review sounds harsh, reach out and let them know you
aim to instruct and appreciate them
@taylor_atx

60. STYLE GUIDES
• Frees your contributors to focus on what’s more valuable,
instead of grammar, consistency, or other issues
• Examples:
• Google Developer Documentation Style Guide
• 18F Content Guide
@taylor_atx

61. Community Engineer at Keen IO
taylor@keen.io
@taylor_atx
TAYLOR BARNETT

62. APPENDIX: LINKS
• How Users Read on the Web article: https://www.nngroup.com/articles/how-users-read-on-the-web/
• Articles: https://www.nngroup.com/topic/writing-web/
• How to Write Documentation for People that Don't Read talk: https://youtu.be/sQP_hUNCrcE
• Designing Great API Docs blog post: http://blog.parse.com/learn/engineering/designing-great-api-
docs/
• Blog plus much more: http://idratherbewriting.com/
• Building navigation for your doc site: 5 best practices talk: https://youtu.be/w-kEmsLwPDE
• Building navigation for your documentation site: 5 best practices in design blog post: http://
idratherbewriting.com/files/doc-navigation-wtd/design-principles-for-doc-navigation/
• Breaking Down Barriers to “Hello World” talk: https://www.slideshare.net/taylorsoitgoes/breaking-
down-barriers-to-hello-world-79181115
• Even Naming This Talk Is Hard talk: https://youtu.be/RFfpkrbkvxc
• Error Messages: Being Humble, Human, and Helpful talk: https://youtu.be/gBBZUATL7Qo
• Don't be a Jerk: Write Documentation blog post: https://ferd.ca/don-t-be-a-jerk-write-
documentation.html
• Docs like Code book: https://www.docslikecode.com/

63. APPENDIX: A NOTE ON OPENAPI
SPECIFICATION
• Spec output can provide a clear source for reference info
about endpoints, parameters, requests, and responses
• Auto generation is a starting point
• Still need more use cases, authorization, why API exists,
more samples, and tutorials
• Think of it as a compliment, a sandbox to play around with
• Two sites isn’t necessarily a bad thing
@taylor_atx