Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Improving developer documentation


Published on

Uwana's talk focuses on how new API documentarians can use internal and external audience feedback to improve the overall quality of their external-facing API documentation. By the end of the talk, technical writers should be able to use internal/external feedback in a balanced way to improve the docs.
Developing robust and intuitive API documentation is a complicated process, especially for those new to that particular type of content. Nevertheless, creating quality documentation is extremely important when it comes to obtaining and retaining users.
While all organizations have their unique quirks, this talk will focus on general commonalities and how to leverage both internal and external user feedback to improve your API documentation.
This talk will help new API documentarians develop and organize useful external content without neglecting internal users in the process. This talk will discuss how to:
Identify your internal audience within your company
Solicit feedback from your internal audience
Collect feedback from your external audience
Weigh each form of feedback appropriately to make improvements for both audiences
By the end of this talk, documentation developers should feel comfortable using both internal and external feedback to improve upon their API documentation.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Improving developer documentation

  1. 1. Improving your developer documentation from the inside-out Uwana Ikaiddi Twitter Date Manager, Developer Documentation @uwikaiddi June 24, 2020
  2. 2. What is developer documentation?
  3. 3. Developer documentation isn’t limited to API reference information. It is a mix of reference and conceptual information that allows organizations to provide an enjoyable developer experience when onboarding newcomers to their APIs.
  4. 4. Who is your audience?
  5. 5. External docs = External audience
  6. 6. External docs ≠ Exclusively external audience
  7. 7. You have an internal audience too.
  8. 8. Steps 1. Identify your internal audience Pinpoint who is using your documentation. 3. Collect external feedback Give your audience a way to contribute. 2. Solicit internal feedback Find out what’s missing. 4. Apply feedback Implement the feedback effectively.
  9. 9. Identify your internal audience
  10. 10. You have more internal readers than you realize.
  11. 11. Your developers ◿ Creating tools using APIs ● Software development kits (SDKs) ● API clients ● Toolkits ● Starter apps ◿ Rely on documentation to know what’s available ◿ Gives confidence that outside developers will have the context they need Identify your internal audience Delete me / place vertical image here
  12. 12. Support agents ◿ Customer Support - guide customers appropriately ◿ Product Support Engineers - support developer questions ◿ Solutions Architects - create solutions using available tools Identify your internal audience Delete me / place vertical image here
  13. 13. ...all the rest! ◿ Marketing ◿ Sales/Sales Engineering ◿ Product Managers ◿ Anyone talking about your APIs to external audiences Identify your internal audience Delete me / place vertical image here
  14. 14. Who is using your docs internally?
  15. 15. Who is asking about you? ◿ Contacting your team regularly ◿ Engaging in conversations about documentation ◿ Asking you if there is documentation addressing a certain question Identify your internal audience Delete me / place vertical image here
  16. 16. Documentation change requests ◿ Creating tickets to request documentation changes ◿ Tagging tickets with labels indicating an effect on documentation Identify your internal audience Delete me / place vertical image here
  17. 17. Go-to-market/release meetings ◿ Invites the documentation teams to meetings regarding new features ◿ Brings up the status/progress of documentation in meetings ◿ Ensures the docs are working cohesively with the rest of the organization Identify your internal audience Delete me / place vertical image here
  18. 18. Who should be aware of your docs?
  19. 19. Who needs to know? ◿ Developer Advocates ◿ Learning/Development - Training ◿ Anyone who uses or discusses APIs regularly Identify your internal audience
  20. 20. Soliciting internal feedback
  21. 21. Creating communication channels for docs Allows others to: ◿ Ask questions about documentation ◿ Make documentation update requests ◿ Facilitate initial discussions about documentation content Solicit internal feedback Delete me / place vertical image here
  22. 22. Create documentation JIRA projects/labels ◿ Tag work that will affect external documentation ◿ Have others submit tickets for changes ◿ Keeps work from falling through the cracks Solicit internal feedback Delete me / place vertical image here
  23. 23. Regular meetings with key stakeholders ◿ Keep up-to-date with upcoming changes ◿ What content needs to be included with upcoming changes Solicit internal feedback Delete me / place vertical image here
  24. 24. Keep all information in one place to track quantity and quality.
  25. 25. Collecting external feedback
  26. 26. Establish audience personas ◿ A persona is a fictional character created to represent a user type that might use a site, brand, or product in a similar way. ◿ Useful when keeping different audiences in mind. Collect external feedback
  27. 27. Establish audience personas ◿ External documentation is not just for developers. ◿ Work with developer advocates to create personas. ◿ Support agents are also great resources for providing common use cases from your potential audience. Collect external feedback
  28. 28. Create a singular place to collect feedback ◿ GitHub issues ◿ Feedback forms ◿ Assessment of feedback ● Is it helpful? ● Is it sufficiently broad? ● Is it actionable? Collect external feedback
  29. 29. Be prepared to receive feedback from multiple areas ◿ Established online community presence ● Slack ● Stack Overflow ● Twitter ◿ Work with developer advocates to catch these. ◿ Consider converting all feedback into a single type in a single place. Collect external feedback
  30. 30. Applying feedback
  31. 31. Common types of feedback Internal ◿ Incomplete information ◿ Not up-to-date ◿ Best practices/troubleshooting External ◿ Not enough content about specific concepts ◿ Unable to find certain information ◿ Popular use cases aren’t covered Apply feedback
  32. 32. Assessing feedback ◿ Most times, different types of feedback don’t interfere. ◿ Use the quality/quantity aspects to help. ◿ Consider creating internal documentation for more in-depth topics that help your internal audience. ● This will create a new doc set for you to manage. ● Keep track of decision-making in case some content needs to switch over. ◿ When in doubt, do what benefits the external user. Apply feedback
  33. 33. Track metrics ◿ Pay attention to the effects of implementing feedback ◿ Drop in product support calls ◿ Increase in the use of certain features, APIs, or tools Apply feedback
  34. 34. Alert your external audience ◿ Changelog for documentation ◿ Social media ◿ Blog posts ◿ Email updates Apply feedback
  35. 35. Tell your internal audience ◿ They should know before your external audience. ◿ Use similar tools as collecting feedback ◿ Clearly define channels meant for informing the audience. ◿ Encourage trust in the process. Apply feedback
  36. 36. Thank you!
  37. 37. References ◿ Unsplash images by: ● Chris Liverani ● Bluehouse Skis ● Luke Chesser ● Christina @ WoCinTechChat