APIStrat 2017
Have you ever read a piece of API documentation and thought it was a mess? Maybe it was incomplete, badly organized, or in general just not great. There’s a good chance it was quickly thrown together by someone who had no idea what they were doing. In this talk, we will discuss the things Taylor wished she knew before starting to dive into the world of writing docs and developer focused content.
We will discuss how people actually read documentation, different types of docs and when they are appropriate, and docs navigation techniques using design principles. Also, we will learn more about the importance of focusing on language, including why naming matters and error messages as a form of documentation. Lastly, we will talk about tools and tactics to enable other team members to write documentation.
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
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
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
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
21.
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
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
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
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
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
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
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
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
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