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

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 24 June. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Uwana Ikaiddi

Development Documentation Manager at BigCommerce

Uwana's presentation



Uwana's slides



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.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.