Improving developer documentation
0 likes339 views
The document emphasizes the importance of developer documentation beyond API reference, highlighting its role in enhancing the developer experience for both internal and external audiences. It outlines steps for improving documentation, including identifying internal audiences, soliciting feedback, and applying that feedback effectively. Additionally, it discusses the necessity of creating a singular feedback collection system and tracking the impact of documentation changes.
Improving developer documentation
- 1. Improving your developer documentation from the inside-out Uwana Ikaiddi Twitter Date Manager, Developer Documentation @uwikaiddi June 24, 2020
- 2. What is developer documentation?
- 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. Who is your audience?
- 6. External docs ≠ Exclusively external audience
- 7. You have an internal audience too.
- 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.
- 10. You have more internal readers than you realize.
- 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. 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. ...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. Who is using your docs internally?
- 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. 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. 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. Who should be aware of your docs?
- 19. Who needs to know? ◿ Developer Advocates ◿ Learning/Development - Training ◿ Anyone who uses or discusses APIs regularly Identify your internal audience
- 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. 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. 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. Keep all information in one place to track quantity and quality.
- 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. 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. 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. 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
- 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. 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. 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. Alert your external audience ◿ Changelog for documentation ◿ Social media ◿ Blog posts ◿ Email updates Apply feedback
- 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. Thank you!
- 37. References ◿ Unsplash images by: ● Chris Liverani ● Bluehouse Skis ● Luke Chesser ● Christina @ WoCinTechChat