Uwana Ikaiddi - Improving Your API Documentation from the Inside-Out

Developer documentation by now includes both reference and conceptual information.
Developer experience when onboarding newcomers and time-to-first-API-call is crucial.

Who is your audience? For example, external docs are the prime source of truth for your internal audience too.

Steps to improve your docs through feedback:

• Identify your internal audience. Who is using your docs?
• Solicit internal feedback. What is missing?
• Collect external feedback. Give a way to contribute.
• Apply feedback to your docs. Implement effectively.

Internal audience

• Who is your internal audience?
  • Developers creating tools utilizing your APIs
  • Customer support, Product support engineers, Solution architects
  • Those talking about your APIs to an external audience: Marketing, Sales / Sales engineering, Product managers, etc.
• How do you know who uses your docs?
  • Those contacting your team regularly or asking for docs on certain topics
  • Change requests on docs - directly requesting or tagging that which will affect docs
  • On go-to-market / release meetings: who invites you, who talks about docs
• Who else should be aware of the status of docs?
  • Developer relations team
  • Learning development / Training
  • Those who use / discuss the APIs regularly

Solicit feedback

• Create communication channels for questions, update requests, initial discussions - a place for others to chime in on ongoing processes.
• Create docs JIRA projects / labels: tag what will have an effect on docs, tickets for changes.
• Regular meetings with key stakeholders: what content needs to be included with upcoming changes, to meld with the overall DX. Align & link dev docs with upcoming marketing, devrel, blog content.
• Keep all information in one place to track quantity and quality. Not all feedback is equal, assess the need and possible contribution to the documentation.

Collecting external feedback

• Can't ask everyone: no direct contact, too many people.
• Establish audience personas (background, tools, behaviors, goals, frustrations). Not only developers! Get insights from developer advocates, support agents.
• One collecting place for all feedback.
• Create predictable habits, patterns on reaching out. For example, GitHub issue links from docs, or a form embedded for direct feedback.
• Assess if feedback is helpful and sufficiently broad use case? Set questions to create actionable answers.
• Many outside sources: all established online community presences are good for candid feedback but require a lot of involvement and resources. Developer advocates, community managers can help to catch such feedback.
• Convert every feedback into the same format.

Some typical feedback

• Insights from internal audiences:
  • Incomplete (more context could be added) or not up-to-date information
  • Suggestions on best practices / troubleshooting
• From external audiences:
  • Not enough information about specific concepts
  • Certain information can’t be found
  • Popular use cases to cover

Applying feedback

• Mostly the internal and external feedback can be both applied, they do not interfere.
• Consider quality and quantity to decide what feedback to act on.
• Consider an internal-only documentation set with more in-depth information. Keep track of the decision-making in case of switching over later.
• In doubt? Always benefit the external user.
• Track metrics on effect of implementing feedback (Less support calls on a topic? Increased use?)
• Alert external audience on changes: change log, social media or blog post, even email updates.
• Tell your internal audience on having acted on their feedback and on changes made.
• Create separate specific channels for your internal- and external audience.