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.
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.
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 eïŹectively.
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 conïŹdence 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
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 eïŹect 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
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 aïŹect 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
26. Establish audience
personas
âż A persona is a ïŹctional
character created to
represent a user type that
might use a site, brand, or
product in a similar way.
âż Useful when keeping
diïŹerent 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 suïŹciently
broad?
â Is it actionable?
Collect external feedback
29. Be prepared to
receive feedback
from multiple areas
âż Established online
community presence
â Slack
â Stack OverïŹow
â 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 speciïŹc concepts
âż Unable to ïŹnd certain information
âż Popular use cases arenât covered
Apply feedback
32. Assessing feedback
âż Most times, diïŹerent 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 beneïŹts the external user.
Apply feedback
33. Track
metrics
âż Pay attention to the
eïŹects of implementing
feedback
âż Drop in product support
calls
âż Increase in the use of
certain features, APIs, or
tools
Apply feedback
35. Tell your
internal audience
âż They should know before
your external audience.
âż Use similar tools as
collecting feedback
âż Clearly deïŹne channels
meant for informing the
audience.
âż Encourage trust in the
process.
Apply feedback