apidays LIVE Hong Kong - The Open API Economy: Finance-as-a-Service & API Ecosystems The three things your developer portal can't live without Ilona Koren-Deutsch, Technical Documentation Manager at Twitch

1. The three things your
developer portal can't
live without
Ilona Koren-Deutsch
API Days Hong Kong
October 2020

2. Introduction

3. This presentation is:
● My thoughts about the subject
● Not representing my employer

4. ● A case for having a developer portal
● Only lecture
This presentation isn’t:

5. ● Interface between API producers and API community
● Enables developers to:
○ Register
○ Explore
○ Consume
○ Get support
● Includes:
○ Documentation
○ Forums
○ Blogs
○ Tutorials
○ Lifecycle information
What is a developer portal?

6. So, those three things?
● Accuracy
● Usefulness
● Security

7. Accuracy

8. First impressions matter
● Halo effect
● Human laziness
● Know your audience

9. Benefits of accuracy
● Reputation for credibility
● Increased speed of development

10. Costs of inaccuracy
● Damage to reputation
● Increased learning curve

11. Get reviews
● Use the 30/90 method
● Find the right reviewers
● Create and use a style guide
● Develop and socialize an SLA for issues

12. Usefulness

13. Different from accuracy
● “Here’s how to use our APIs in case you’re unfamiliar or
have limited experience with us and a searchable
reference in case you need to look up something specific.”
● “Here’s literally every word the developers told us about
every obscure application of our API and a reference
because we’re sure you’ll want to read more.”

14. ● Time-sensitive
● Sustainable
● Accessible
● Inclusive
● Discoverable
What makes information useful

15. Time-sensitive
● Feature ime-sensitive content
○ Breaking news
○ Event information
○ API uptime
● Avoid content delay syndrome

16. Sustainable
● Update factual content with any new information
● Delete content that no longer holds true
● Maintain a change log

17. Accessible
● Ensure that readers can navigate your whole site using
only a keyboard, without a mouse or trackpad
● Break up large sections of text and use whitespace
liberally
● Use meaningful link text
● Avoid directional language
● Provide closed-captioning for video
● Write for users of screen readers
● Use images to illustrate rather than provide new
information

18. Inclusive
● Avoid ableist language
● Don’t use gendered language
● Avoid unnecessarily violent language and images
● Use socially-conscious engineering terms
● Eliminate condescending language
● Use online tools
● Ask people

19. Discoverable
● Site traffic
● On-site time
● SEO

20. Security

21. API security strategy
● Validate parameters
● Apply explicit threat detection
● Turn on SSL everywhere
● Apply rigorous authentication and authorization
● Use proven solutions

22. Manage user identities
● Types of users
○ Built-in directory
○ SSO integration

23. Manage access permissions
● Internal only
● Private
● Public

24. ● Enforce consistent access control
● Avoid insecure workarounds
Internal portals need security too

25. Trust

26. Engagement
● Satisfaction
● Proficiency level
● Usage

27. Retention
● Reward active participation
● Add useful new content
● Excellent search
● Be the authority

28. In conclusion

29. Your turn

30. LinkedIn: linkedin.com/in/ilonakd
Email: ilona@ikd.io
Twitter: @nitsekees
Discord and GitHub: cycene
Contact me: