Downloaded 14 times
Uploaded byBrandon West
(API) Docs for Developers
Brandon introduces himself as the creator of documentation for developers. The goals of documentation are to make users successful, allow self-service, and reduce support overhead. There are different types of documentation like descriptive, reference, tutorials, and interactive. Documentation requires technical writers as well as engineers and must be organized, formatted well, and kept up to date like code. Feedback from users and secondary sources should be considered to continuously improve documentation.
(API) Docs for Developers
- 1. Docs for Developers Hi, I’m Brandon. @brandonmwest brandon.west@sendgrid.com
- 2. Goals of Docs 1. Make the user a hero
- 3. Goals of Docs 2.Let customers self serve
- 4. Goals of Docs 3.Reduce support overhead
- 5. Goals of Docs 1.Make the user a hero 2. Let customers self serve 3. Reduce support overhead
- 6. TYPES of Docs • Descriptive • Reference / Code • Tutorials • Interactive
- 7. Who should Write Docs “Most engineers can’t write a single coherent sentence, never mind string together a paragraph.”
- 8. TYPES of Docs • Descriptive • Reference / Code • Tutorials • Interactive
- 9. Docs developer A techwriter isn’t enough. Ninjas need not apply.
- 10.
- 11. structure Ifyour content is not organized and easy to find, it’s not as valuable.
- 12. MARKUP and FORMAT The layout and formatting of the docs are MORE important than the words.
- 13. DOCS ARE MUTABLE Docs are alive, just like the code and DB schema
- 14. Do not Repeat YOURSELF
- 15. Keep it loosely Coupled Don’t document the UI. Don’t document third parties.
- 16. Tighten the feedback loop • Let users submit feedback. • Pay attention to secondary sources, e.g. Stack Overflow and GitHub.
- 17. Do not relyon robots Automatic documentation is good... but not good enough.
- 18. Docs for developers Thanks! @brandonmwest brandon.west@sendgrid.com
Editor's Notes
- #2 Anecdote about Denver Post image\n\nMy background and current job, how that led me to docs\n\nI’ve spent a big part of the last year working on documentation for SendGrid. I’ve learned a lot of things. \n\nMost of this will be about documenting an abstraction layer e.g. an API. If you have a static, concrete product this might not be as helpful\n
- #3 Give the user the weapons they need to do the thing they need to do, quickly. \n\nFor the most basic use case for you app, you want users to go from “I don’t know what I’m doing” to “yes! it works!” in five minutes or less. -- mention Jeff Lawson from Twilio, John Musser from Programmable Web\n\nIf there are other barriers besides docs that prevent you from doing this, work on removing them.\n
- #4 Developers are people who need to get things done. They don’t want to call or email or use live chat to figure out how to do something.\n\nThis can mean a lot of different\n
- #5 Just as devs don’t want to call or email or use live chat, as a company we don’t want them to either. It doesn’t scale.\n\nDuring SendGrid’s first year of existence we had a “premium” support subscription, that gave you access to Tim Jenkins’ cell phone number. \n\n“Just like quick-and-dirty coding decisions can lead to technical debt, poor documentation can lead to operational debt.” -- Kevin Burke, Twilio\n\nImage: Konami LaserScope\nAll a user was required to do was say "fire" and the gun, supposedly, would fire at the target. However, the peripheral would often malfunction and fire at any background noise, which led to the negative reception the LaserScope eventually received.\n
- #6 Your docs are, in a way, your marketing materials for developers. I want to be clear that I don’t mean you should put marketing speak into your docs. I mean that if your docs are good, developers are much more likely to trust and use your product. If your docs meet the first two goals, there’s a good chance the users will be happy.\n
- #7 Descriptive -- we solve problem X, and you get benefit Y\n\nReference / Code -- technical details and sample implementations\nTutorials -- end-to-end walkthroughs of various use cases (shout out to twilio)\n\nInteractive -- Let the user play with the system without code (shout out to Mashery)\n
- #8 I think this is a little bit insulting and more than a little untrue. \nAlso this was used as a thesis as to why bad software gets developed, which seems a bit absurd\n\nIf not engineers, then that leaves you with a technical writer.\n
- #9 The first type is probably the least important -- most of that should be covered by your marketing department. The goal of descriptive docs should be to funnel users to the areas of the docs that are most relevant to them. For example, on SendGrid it’s broken down along “marketing” and “technical/developer” users\n\nThe second part requires engineering resources -- either to pass info along to the writer, or to write the code samples.\n\n“The vast majority of people who visit your documentation are there not to learn more about your fascinating product. They are there to find out how to get something done”\n\n“You could argue that your API is one big abstraction, and that’s kind of the point. However, when teaching developers, try to remove as many abstractions as possible.” -- Kevin Burke, Twilio\nWhat does that sound like? Implementing an API. Who knows how to do that? Devs.\n\n3 of the 4 categories require developers. So who writes or manages docs?\n
- #10 Developers require docs, and so docs require developers. \n\n“The best person to document is the builder. After all, who knows the system better than the system builder?” \n-- I disagree. The person who built it is sometimes too close to the problem, similar to a UI person testing his own interface. “A” builder should test it, but not “THE” builder.\n\nIf a tech writer gets feedback from a user that a code example is wrong, they have to ask an engineer to vet it. \n\nIf a new API endpoint is being released and it is inconsistent with the rest of the API, a tech writer might not notice or know why it matters.\n\nA developer can also address platform-level problems that are separate from the content concerns.\n\nIf you can become this person you’ll make yourself very valuable. Be the ditch digger, not the ninja.\n
- #11 Engineers are going to be heavily involved in the documentation process no matter how you go about it. But that’s not a bad thing, at all.\n\nLet’s consider how we can apply the things we already know from software architecture to the docs.\n
- #12 Engineers are used to structure and organization. Conventions are a requirement for all engineering projects - file locations, names, etc.\n\nClearly defined structure and hierarchy. Parent nodes should be easily identifiable. Code samples should be well formatted and easy to read. \n\nMake things consistent. If you are documenting an API endpoint and method, make it look like all the other ones in your docs.\n\nMake things searchable.\n
- #13 Guy who wrote PHD on Docs:\n“Assume that most users will not actually read the documentation of the functions they call. In fact, the more intuitive your API is, the less chances are someone would read the documentation.”\n\nI think this is actually true of all web content\n\nThat means your tech writer must know HTML or Markdown etc at a minimum\n\n- Tables of parameters, example calls/responses etc are not words\n- Inverted pyramid style -- most important information up top\n- Use structure to give context, not words\n\n
- #14 Implications\n have to build smart constraints into the system\n version control is important\n The game might change as you scale - 1 endpoint vs 25\n Decide if you need continuous deploy, automated tests, etc at scale\n\n\nAll of these things will inform the platform you choose. \n*anecdote re: wordpress failing*\n\n\n
- #15 This screen shows up 7 times.\n\nIf you have to change something you don’t want to be searching through the docs to find all the instances of that change. It also makes your search results less meaningful, and having the same information in multiple places can distract your audience.\n\nUse hyperlinks.\n
- #16 Try to only document the things that you can control, or at least the things where you can tap into the change flow. Inaccurate information is worse than no information because it creates false hope.\n\nIf your UI requires documentation, you should probably simplify it. (easy for me to say!) And in cases where you can’t simplify it, build the guidance into the UX. \n\nNote that this applies more to web apps, since real “shipped” code (e.g. outlook) is unlikely to change and therefore screenshots etc can be used.\n
- #17 Treat your docs as an access point for your community.\n\n(remember the third goal of docs -- reduce overhead)\nSpeak with your support team regularly to assess what is working \n\nGood engineers know that iteration is the a big part of a successful product, and a big part of successful iteration is a working feedback loop.\n\nKeep in mind that you can’t please everyone. Our docs used to be less than good and we’d often receive praise for them.\n
- #18 Your company has a personality and a voice. Or at least it should. Make sure your documentation is human -- keep your users interested. \n\n“Chunky Bacon” vs “foo bar”\n
- #19 \n