"Developer eXperience (DX) is crucial for the success of an API. That is why API teams build developer portals where the team can publish their API reference. This is where most teams fail. A great developer experience requires more than reference docs. In this talk you’ll learn about the curious world of API docs, exploring the different documentation components you need for a great developer experience through a series of less known facts and non-obvious insights that I've collected over the course of 2 years of research. Should you automatically generate your SDKs? Is there a difference between guides and tutorials? Are reference docs sufficient for your API docs MVP? Is Swagger the ultimate API reference documentation format? Find out if you know the answers to these and many more questions and make a chance to win some Belgian chocolates!"

1. Developer portals:
Where docs become DX
Kristof Van Tomme
co-Founder/CEO
Ghent, Belgium
@kvantomme
kristof@pronovix.com

2. ●
●
●
●
●
●

4. Distill & Share
Developer Portal
Best Practices

5. Working on an open source Drupal developer portal product

6. 1. What is a developer portal?

7. All your docs, not just your API reference!

8. A developer portal is where you publish all of your API’s docs

10. An interface for your API strategy

11. Dev portals are a communication nexus for all API stakeholders
●
●
●

12. And your dev portal plays a key role as a trust signal

13. 2. API friction destroys API value

14. Bruno Pedro’s article about API friction got me thinking

15. perceived API value
API friction
API usage =

16. 4. What is Developer eXperience?

17. 1
Developer eXperience =
API friction

18. 2. Evaluate
3. Get started
1. Discover/Research
4. Develop & Troubleshoot
5. Celebrate
6. Maintain

19. API usage = perceived API value x DX

20. API usage = perceived API value x DX
Developer portal

21. 5. What do you need on your dev portal?

22. If you write regularly, blogs can be great content incubators

23. Landing pages help to find and navigate your documentation

24. Tutorials show how to do something -> get started

25. Guides show problems that your product solves -> evaluate

26. Conceptual docs explain difficult or unintuitive concepts

27. Reference docs are crucial for development/troubleshooting

31. ●
●
●
●
●
●
●
●
●

32. 6. What is the best way to build SDKs?

33. Find out at the extended version of this talk on Thursday!

34. Summary

35. A developer portal is where you publish your API’s docs

36. All your docs, not just your API reference!

37. Dev portals are a communication nexus for all API stakeholders
●
●
●

38. API usage = perceived API value x DX
Developer portal
Dev portals increase both your APIs perceived value and DX

39. ●
●
●
●
●
●
●
●
●

40. Want more?

42. Developer portal mailing list
bit.ly/devportals

43. Questions?

44. https://commons.wikimedia.org/wiki/File:CSIRO_ScienceImage_6586_A_frame_from_a_beehive_at_a_cherry_farm_near_Young_New_South_Wales.jpg
https://commons.wikimedia.org/wiki/File:Lines_(call_center)_by_Vassilis_Mazomenos.jpg
https://commons.wikimedia.org/wiki/File:FirstBankofUS00_crop.jpg
https://commons.wikimedia.org/wiki/File:Cat_in_a_big_box.jpg
https://commons.wikimedia.org/wiki/File:Wikimedia_Hackathon_2013,_Amsterdam_-_Flickr_-_Sebastiaan_ter_Burg_%2828%29.jpg
https://commons.wikimedia.org/wiki/File:Handshake_duisenberg_school_of_finance.jpg
https://commons.wikimedia.org/wiki/File:Times_Square,_New_York_City_(HDR).jpg
https://commons.wikimedia.org/wiki/File:WinterArmenia3.JPG
https://commons.wikimedia.org/wiki/File:Rest.wikimedia.org_Swagger_API_doc.png
https://commons.wikimedia.org/wiki/File:Lego_instructions.jpg
https://commons.wikimedia.org/wiki/File:OED2_volumes.jpg
https://commons.wikimedia.org/wiki/File:Socialmedia-pm.png
https://commons.wikimedia.org/wiki/File:NASA_Organizational_Chart_November_1,_1961.jpg
https://commons.wikimedia.org/wiki/File:Grand_Study_Hall,_New_York_Public_Library_(5914733818).jpg
https://commons.wikimedia.org/wiki/File:Modern_warehouse_with_pallet_rack_storage_system.jpg
https://commons.wikimedia.org/wiki/File:Slagbomen_met_vouwhekken.jpg
Attribution I

45. Attribution II
https://commons.wikimedia.org/wiki/File:Parking_meter.jpg
https://commons.wikimedia.org/wiki/File:Interface_Message_Processor_Front_Panel.jpg
https://twitter.com/conways_law?lang=en
https://commons.wikimedia.org/wiki/File:Hands_Across_the_Divide_-_geograph.org.uk_-_478600.jpg
https://commons.wikimedia.org/wiki/File:Blueprint_reading;_a_practical_manual_of_instruction_in_blueprint_reading_through_the_analysis_of_typical_plate
s_with_reference_to_mechanical_drawing_conventions_and_methods,_the_laws_of_projection,_(14780705985).jpg
https://commons.wikimedia.org/wiki/File:Blueprint_for_Victory_-_NARA_-_534666.jpg
https://commons.wikimedia.org/wiki/File:Neil_Armstrong_and_Deke_Slayton_in_discussion.jpg
https://commons.wikimedia.org/wiki/File:WD40_english.JPG
https://commons.wikimedia.org/wiki/File:Capt._Nicole_Malachowski,_F-15E_female_pilot,_looks_over_checklists_before_flying_a_sortie_1763646018.jpg
https://commons.wikimedia.org/wiki/File:CRS-8_first_stage_landing_(26326588761).jpg
https://commons.wikimedia.org/wiki/File:24h_egg_self_service,_Rohrbach_bei_Sankt_Florian.JPG