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.

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?

5. External docs
=
External 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.

9. Identify your internal
audience

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

20. Soliciting internal
feedback

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.

25. Collecting external
feedback

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

30. Applying 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