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 effectively.
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
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
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
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
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