Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Reference docs are
not enough...
even for internal developer portals
István Zoltán Szabó
Senior Technical Writer
1
@szabos...
2
“Grow and help grow”
33
4
My colleagues, who make it possible for me to be here
5
Reference docs are not enough…
● What is a developer portal?
● Doc types on devportals
● What API description pages are?...
WHAT IS A
DEVELOPER
PORTAL?
66
7
A DEVELOPER
PORTAL IS
A PLACE FOR ALL
THE
STAKEHOLDERS OF
YOUR APIS
7
8
A developer portal is the home of your API program and a
strategic tool for making it a success.
9
● Internal developer portals
● External developer portals
Developer
portals
10
● They are not available publicly
● Audience: company members
Internal
portals
11
● They are available publicly
● Audience: external developers &
decision makers
● Potential profit centers
External
por...
DOCUMENTATION
TYPES
ON DEVELOPER
PORTALS
1212
TWO MAIN DOC
TYPES
1. REFERENCE DOCS 2. SUPPORTING DOCS
13
TWO MAIN DOC
TYPES
1. REFERENCE DOCS 2. SUPPORTING DOCS
14
- Open API/Swagger,
RAML, API Blueprint
- functions
- classes
-...
15
DEVELOPER
PORTALS ARE
MORE THAN
REFERENCE DOCS
15
16
SUPPORTING
DOCUMENTATION
CONCEPTS,
HOW-TO GUIDES,
TUTORIALS,
GLOSSARIES,
FAQ,
API DESCRIPTION.
16
API
DESCRIPTION
1717
18
● Helps to decide which API to use
● Audience is heterogeneous
○ Developers
○ Decision makers
● Important to target man...
19
API description pages give an answer to the question:
Is this something that I’m really looking for?
20
● The API’s most important
functions and features
● Benefits
● Requirements
● Common fields of operation
API
descriptio...
API
Description
is something
between
technical
description
and
marketing
material.
Marketing
material
Technical
descriptio...
22
WRITING API
DESCRIPTION
22
23
CONSISTENCY
IS A TRUST
SIGNAL
23
24
USE A
TEMPLATE TO
ENSURE
CONSISTENCY
Pronovix confidential and proprietary 24
25
BEFORE
WRITING:
INTERVIEW
(IF YOU HAVE
THAT LUXURY)
25
26
BEFORE
WRITING: API
REFERENCE
26
27
● API name
● Description
● Version number
API
Description
template ● Category / Tags
● Benefits
● What it is
● Why use ...
28
1. API NAME
28
[API Name]
Nostromo API
29
2.
DESCRIPTION
29
30
3. VERSION
NUMBER
30
31
4. CATEGORY /
TAGS
31
32
5. BENEFITS
32
33
6. WHAT IT IS
33
34
7. WHY USE IT
34
35
8. HOW IT
WORKS
9. HOW TO
USE
35
36
10.
REQUIREMENTS
11. PRICING
36
37
AFTER
WRITING:
REVIEW
37
38
AFTER
WRITING:
NON-TEXTUAL
CONTENT &
CTAS
38
39
API
DESCRIPTION
ON INTERNAL
PORTALS
39
40
Lot of APIs: orientation, gathering information, improve DX.
Internal
portals
41
Few APIs: easy to generate, improve DX.
Internal
portals
LET’S VOTE!
1. “API description”
2. “API overview”
3. “API summary”
4. Other
42
Images & screenshots
unsplash.com
Pixabay.com
Image on slide 7 is the property of DC Comics and
Warner Bros.
The images on...
Thank you!
Developer portal mailing list
bit.ly/devportals
44
45
Upcoming SlideShare
Loading in …5
×

APIdays Paris 2018 - Reference Docs are not enough… Even for Internal Developer Portals, István Zoltán Szabó, Senior Technical Writer, Pronovix

101 views

Published on

Reference Docs are not enough… Even for Internal Developer Portals
István Zoltán Szabó, Senior Technical Writer, Pronovix

Apply to be a speaker here - https://apidays.typeform.com/to/J1snsg

Published in: Technology
  • Be the first to comment

  • Be the first to like this

APIdays Paris 2018 - Reference Docs are not enough… Even for Internal Developer Portals, István Zoltán Szabó, Senior Technical Writer, Pronovix

  1. 1. Reference docs are not enough... even for internal developer portals István Zoltán Szabó Senior Technical Writer 1 @szabosteve steve@pronovix.com
  2. 2. 2 “Grow and help grow”
  3. 3. 33
  4. 4. 4 My colleagues, who make it possible for me to be here
  5. 5. 5 Reference docs are not enough… ● What is a developer portal? ● Doc types on devportals ● What API description pages are? ● Writing API description About the talk
  6. 6. WHAT IS A DEVELOPER PORTAL? 66
  7. 7. 7 A DEVELOPER PORTAL IS A PLACE FOR ALL THE STAKEHOLDERS OF YOUR APIS 7
  8. 8. 8 A developer portal is the home of your API program and a strategic tool for making it a success.
  9. 9. 9 ● Internal developer portals ● External developer portals Developer portals
  10. 10. 10 ● They are not available publicly ● Audience: company members Internal portals
  11. 11. 11 ● They are available publicly ● Audience: external developers & decision makers ● Potential profit centers External portals
  12. 12. DOCUMENTATION TYPES ON DEVELOPER PORTALS 1212
  13. 13. TWO MAIN DOC TYPES 1. REFERENCE DOCS 2. SUPPORTING DOCS 13
  14. 14. TWO MAIN DOC TYPES 1. REFERENCE DOCS 2. SUPPORTING DOCS 14 - Open API/Swagger, RAML, API Blueprint - functions - classes - return types - arguments -parameters
  15. 15. 15 DEVELOPER PORTALS ARE MORE THAN REFERENCE DOCS 15
  16. 16. 16 SUPPORTING DOCUMENTATION CONCEPTS, HOW-TO GUIDES, TUTORIALS, GLOSSARIES, FAQ, API DESCRIPTION. 16
  17. 17. API DESCRIPTION 1717
  18. 18. 18 ● Helps to decide which API to use ● Audience is heterogeneous ○ Developers ○ Decision makers ● Important to target managers API description
  19. 19. 19 API description pages give an answer to the question: Is this something that I’m really looking for?
  20. 20. 20 ● The API’s most important functions and features ● Benefits ● Requirements ● Common fields of operation API description explains
  21. 21. API Description is something between technical description and marketing material. Marketing material Technical description API Description 21
  22. 22. 22 WRITING API DESCRIPTION 22
  23. 23. 23 CONSISTENCY IS A TRUST SIGNAL 23
  24. 24. 24 USE A TEMPLATE TO ENSURE CONSISTENCY Pronovix confidential and proprietary 24
  25. 25. 25 BEFORE WRITING: INTERVIEW (IF YOU HAVE THAT LUXURY) 25
  26. 26. 26 BEFORE WRITING: API REFERENCE 26
  27. 27. 27 ● API name ● Description ● Version number API Description template ● Category / Tags ● Benefits ● What it is ● Why use it ● (How it works) ● How to use ● Requirements ● (Pricing)
  28. 28. 28 1. API NAME 28 [API Name] Nostromo API
  29. 29. 29 2. DESCRIPTION 29
  30. 30. 30 3. VERSION NUMBER 30
  31. 31. 31 4. CATEGORY / TAGS 31
  32. 32. 32 5. BENEFITS 32
  33. 33. 33 6. WHAT IT IS 33
  34. 34. 34 7. WHY USE IT 34
  35. 35. 35 8. HOW IT WORKS 9. HOW TO USE 35
  36. 36. 36 10. REQUIREMENTS 11. PRICING 36
  37. 37. 37 AFTER WRITING: REVIEW 37
  38. 38. 38 AFTER WRITING: NON-TEXTUAL CONTENT & CTAS 38
  39. 39. 39 API DESCRIPTION ON INTERNAL PORTALS 39
  40. 40. 40 Lot of APIs: orientation, gathering information, improve DX. Internal portals
  41. 41. 41 Few APIs: easy to generate, improve DX. Internal portals
  42. 42. LET’S VOTE! 1. “API description” 2. “API overview” 3. “API summary” 4. Other 42
  43. 43. Images & screenshots unsplash.com Pixabay.com Image on slide 7 is the property of DC Comics and Warner Bros. The images on the mock page are the properties of 20th Century Fox. 43
  44. 44. Thank you! Developer portal mailing list bit.ly/devportals 44
  45. 45. 45

×