A presentation given by Gertrude Chilufya Westrin, Developer Advocate, Qlik, at our 2023 Platform Summit, October 17-18, 2023

1. Navigating API Documentation:
Tips from the Trenches
By Gertrude Westrin

2. About Me
➔ Developer Advocate at Qlik and The
Tech Girl Podcast host
➔ Originally from Zambia
➔ Mother to a 4 year old son

3. Have you ever struggled with API
Documentation?

4. What is your greatest API
documentation struggle?

5. API documentation???

6. API documentation is a set of
mostly written functions of an API
and how to use it.

7. Why do I care?
★ Lack of Consistency
★ No clear descriptions
★ Difficult to get started

8. What I have learnt
Tip 1: Read the documentation
- Understand endpoint definitions
- Status and error codes
- Limitations of the APIs
- Authentication

9. What I have learnt
Tip 2: What is the use case?
- Who will use this? It helps to clearly segment the audience
- Show multiple use of endpoints to achieve a goal for instance making
an or order for payments API or lead funnel for marketing
- Accessibility

10. What I have learnt
Tip 3: Sandbox/ Runable code
- It might be beneficial to get input from others functions, eg presales
*Lowest possible barrier to getting started
- Be more descriptive/instructional, for instance;
A. Download this code
B. Replace API Key
C. Run Code

11. What I have learnt
Tip 4: Having consistency across documentation, coverage and logic.
- Language and consistency examples eg Java .Net capabilities and
idiomatic code.
- Developers for developers: Not all users of docs have experience
with APIs so keep it entry level, maybe use doc tools
- Keep the portal flexible enough to adapt to changes eg support of
other programming languages or API types.

12. What is your preferred way of learning about
platform APIs and usage? Videos, blogs,
tutorials, talks, workshops, conferences?

13. What I have learnt
Tip 5: Don’t sleep on the changelog
Quickly scan for any changes, for instance:
- Deprecation
- Breaking changes,
- New required parameters,
- Versioning,
- New endpoints etc

14. What I have learnt
Tip 6: Maintenance
- Update strategy
*Analyse what endpoints might require more tutorials, details or
improvements.
- Automate the process?
*From OpenAI to postman

15. What I have learnt
Tip 7: Leave it better than you found it
- Create a PR
- Raise an issue
- Give feedback
*Broken links
*Unusual/unexpected behaviour
*Great docs

16. Where to Find Me
LinkedIn: Gertrude Chilufya Westrin

17. “If a human has to explain an API and
how to use it, the documentation has
not served its purpose”
Sharath-Medium.