How can you help developers to meet their needs when visiting a developer portal? How can you improve Developer eXperience via documentation types? What developer marketing practices help to reduce API friction?

1. Architecting Developer
eXperience
What docs does a developer portal need?
Kathleen De Roo
@kat_deroo
Technical Writer & Junior Information Architect

2. Thank you!

3. Content
Developer portals
Tasks to do
Developer eXperience
Reduce API friction & engage users
Documentation eXperience
Documentation types along the
developer journey stages

4. Inspire all of your
developers

5. What is a developer portal?
http://bit.ly/apidocs_vs_devportal
Business
Goals
APIsStakeholders

6. The developer portal as a self-service support hub

7. Support to get started
Visa

8. The developer portal as a trust signal

9. Legal documentation is a trust signal
LinkedIn

10. Pricing information is a trust signal
Keen IO

11. The developer portal as a documentation database

12. The developer portal enables user journeys

13. The downstream developer journey of the
developer that uses the API

14. Developers with
different skills & background knowledge

15. Developers can have different needs & goals

16. Address developer journey stages

17. What is Documentation eXperience?
bit.ly/devportalmvp
Doc X

18. Overview (landing) pages
Stage 1: Discover/Research
How can this portal help me to solve my specific task?
Doc X

19. Doc X
Overview page: questions to answer

20. API product/service focused overview page
ABN Amro Amazon
Doc X

21. Overview page with integrated API references
Clearbit
Doc X

22. Overview page with separate API references
Stripe
Doc X

23. Overview page with a focus on coding languages
Dropbox Heroku
Doc X

24. Overview page with a focus on documentation types
DigitalOcean
Algolia
Doc X

25. Overview page with a focus on use cases / thematic areas
PayPal Twitter
Doc X

26. Overview page with a regional focus
Facebook
Doc X

27. Overview pages that combine categories
CenturyLink Doc X

28. Trust signals in documentation
Blogs, use cases
Worked examples
Stage 2: Evaluate
Can I trust this organization’s commitment to its APIs?
Doc X

29. A changelog is a trust signal
Twilio
Doc X

30. Blogs and use cases
Slack
Twilio
Doc X

31. Worked example
Redgate
Doc X

32. Tutorials
How-to guides
Concepts
SDKs
Topic guides
Stage 3: Get Started
Where do I begin?
Doc X

33. Tutorial, how-to guide
Apigee
DigitalOcean
Doc X

34. Twilio
Doc X
Tutorial

35. Conceptual documentation
Chargify
Doc X

36. Software Development Kits (SDKs)
Braintree
Doc X

37. References
FAQs
Community page
Forum
Stage 4: Develop & Troubleshoot
Do I know everything to make this work?
Doc X

38. References
Keen IO
1 2 3
Doc X

39. Audience focused FAQs
Dwolla
Doc X

40. MasterCard
Doc X
Support page → FAQ

41. Peer-to-peer support
Cisco
Doc X
Redgate

42. Blog — use cases
Community Page
Stage 5: Celebrate
Will they care about my work?
Doc X

43. Twilio
Blog, use cases
Doc X

44. Community page
Keen IO
Doc X

45. Changelog
Status page
Versioning info
Legal docs
Stage 6: Maintain
How hard will it be to keep this running?
Doc X

46. API status
MailChimp
Doc X

47. Addressing user needs along journey stages
results in a better overall experience

48. The developer portal as a DevRel tool

49. What is Developer eXperience?
http://bit.ly/API_friction
DX

50. DX is about engagement, achievement & the right tools

51. How can you reduce API friction and
engage & motivate users
along the developer journey?
http://bit.ly/API_friction
DX

52. API catalog
Direct users
Stage 1: Discover & Research
How can this portal help me to solve my specific task?
DX

53. Descriptions, filtering
Citi
Erste
DX

54. Instagram
Direct users
DX

55. Try-out / test options
Stage 2: Evaluate
Can I trust this organization’s commitment to its APIs?
DX

56. Adyen
Dwolla
DX
Try-out zone

57. Mailjet
Google
DX
Demos, samples

58. Erste
DX
Sandbox, console

59. Registration
API key / token provision
Community documentation
Games
Stage 3: Get started
Where do I begin?
DX

60. ABN Amro
Mapbox
Algolia
DX
Registration, token, API key
Mapbox

61. RapidAPI
Slack
Keen IO
DX
Ask for feedback, community documentation

62. Twilio
DX
Get started game

63. Ask for feedback
Support options in one place
(Discussion) forum
Stage 4: Develop & Troubleshoot
Do I know everything to make this work?
DX

64. Deutsche Bank
DX
Ask for feedback
Citi

65. Capital One
DX
Make handling code easy

66. Starling Bank
DX
Support options in one place
Keen IO

67. Dwolla
DX
Discussion forum

68. Organize events
Pay for work
Celebrate active users
Voting system
Stage 5: Celebrate → Engage
Will they care about my work?
DX

69. Capital One
Spotify
DX
Organize hackathons / events

70. DigitalOcean
DX
Pay for work

71. Apigee
DigitalOcean
DX
Community pages: voting system / celebrate active users

72. Changelog
API status page
Legal docs
Future plans
Stage 6: Maintain
How hard will it be to keep this running?
DX

73. Algolia
DX
Changelog on overview page

74. Nordea
DX
Reveal future plans

75. Takeaways

76. Inspire all of your
developers

77. Benefits
when you
take care of
Developer
eXperience
Higher
perceived
API value
Higher API
usage
Less friction Engaged
API
advocates
Developer
eXperience

78. Downstream
dev journey
stages
Think about...
Documentation
components
Discover &
Research
Landing page focus & structure Landing page, blog
Evaluate
Trust signals
Try-out options, demos, samples
Blog articles, use cases,
worked examples,
changelog, legal docs
Get Started
Sign-up and API key/token provisioning process
Ask for feedback, let users commit
Interactive tools
Tutorials, how-tos,
concepts, SDKs, topic
guides
Develop &
Troubleshoot
Audience focused support,
interactive contact form
Interview users at events, ask for feedback
References, FAQs,
discussion forum
Celebrate
Let users cover niche problems
Celebrate active users, reward them
Organize events/hackathons
Blog articles,
community page, use
cases
Maintain
Trust signals
Audience focused info
Reveal future plans
Legal docs, changelog,
status page, community
page
Give users
what they
need
&
Improve
Developer
eXperience

79. Image, screenshot and other
attributions
Unsplash.com
Developer portals
ABN Amro, Adyen, Algolia, Amazon, Apigee,
Braintree, Capital One, CenturyLink, Chargify, Cisco,
Citi, Clearbit, Deutsche Bank, DigitalOcean, Dropbox, Dwolla,
Erste, Facebook, Google, Heroku, Instagram, Keen IO,
LinkedIn, MailChimp, Mailjet, Mapbox, MasterCard,
Nordea, PayPal, RapidAPI, Redgate, Slack, Spotify, Starling Bank,
Stripe, Twilio, Twitter, Visa.
Research results of Meng et al. (Merseburg University of Applied Sciences)

80. Thank you!
Newsletter
bit.ly/devportals
Read more
pronovix.com/articles

81. Downstream
dev journey
stages
Think about...
Documentation
components
Discover &
Research
Landing page focus & structure Landing page, blog
Evaluate
Trust signals
Try-out options, demos, samples
Blog articles, use cases,
worked examples,
changelog, legal docs
Get Started
Sign-up and API key/token provisioning process
Ask for feedback, let users commit
Interactive tools
Tutorials, how-tos,
concepts, SDKs, topic
guides
Develop &
Troubleshoot
Audience focused support,
interactive contact form
Interview users at events, ask for feedback
References, FAQs,
discussion forum
Celebrate
Let users cover niche problems
Celebrate active users, reward them
Organize events/hackathons
Blog articles,
community page, use
cases
Maintain
Trust signals
Audience focused info
Reveal future plans
Legal docs, changelog,
status page, community
page
Give users
what they
need
&
Improve
Developer
eXperience