Things I Wish People Told Me About Writing Docs
•
6 likes•1,816 views
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.
Recommended
More Related Content
What's hot
Similar to Things I Wish People Told Me About Writing Docs
Similar to Things I Wish People Told Me About Writing Docs (20)
Recently uploaded
Recently uploaded (20)
Things I Wish People Told Me About Writing Docs
- 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
- 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
- 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
- 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
- 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
- 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
- 37. @taylor_atx
- 39. 😨 😨 @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
- 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
- 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