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
“Grow and help grow”

3.
33

4.
4
My colleagues, who make it possible for me to be here

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.
WHAT IS A
DEVELOPER
PORTAL?
66

7.
7
A DEVELOPER
PORTAL IS
A PLACE FOR ALL
THE
STAKEHOLDERS OF
YOUR APIS
7

8.
8
A developer portal is the home of your API program and a
strategic tool for making it a success.

9.
9
● Internal developer portals
● External developer portals
Developer
portals

10.
10
● They are not available publicly
● Audience: company members
Internal
portals

11.
11
● They are available publicly
● Audience: external developers &
decision makers
● Potential profit centers
External
portals

12.
DOCUMENTATION
TYPES
ON DEVELOPER
PORTALS
1212

13.
TWO MAIN DOC
TYPES
1. REFERENCE DOCS 2. SUPPORTING DOCS
13

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
DEVELOPER
PORTALS ARE
MORE THAN
REFERENCE DOCS
15

16.
16
SUPPORTING
DOCUMENTATION
CONCEPTS,
HOW-TO GUIDES,
TUTORIALS,
GLOSSARIES,
FAQ,
API DESCRIPTION.
16

17.
API
DESCRIPTION
1717

18.
18
● Helps to decide which API to use
● Audience is heterogeneous
○ Developers
○ Decision makers
● Important to target managers
API
description

19.
19
API description pages give an answer to the question:
Is this something that I’m really looking for?

20.
20
● The API’s most important
functions and features
● Benefits
● Requirements
● Common fields of operation
API
description
explains

21.
API
Description
is something
between
technical
description
and
marketing
material.
Marketing
material
Technical
description
API
Description
21

22.
22
WRITING API
DESCRIPTION
22

23.
23
CONSISTENCY
IS A TRUST
SIGNAL
23

24.
24
USE A
TEMPLATE TO
ENSURE
CONSISTENCY
Pronovix confidential and proprietary 24

25.
25
BEFORE
WRITING:
INTERVIEW
(IF YOU HAVE
THAT LUXURY)
25

26.
26
BEFORE
WRITING: API
REFERENCE
26

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
1. API NAME
28
[API Name]
Nostromo API

29.
29
2.
DESCRIPTION
29

30.
30
3. VERSION
NUMBER
30

31.
31
4. CATEGORY /
TAGS
31

32.
32
5. BENEFITS
32

33.
33
6. WHAT IT IS
33

34.
34
7. WHY USE IT
34

35.
35
8. HOW IT
WORKS
9. HOW TO
USE
35

36.
36
10.
REQUIREMENTS
11. PRICING
36

37.
37
AFTER
WRITING:
REVIEW
37

38.
38
AFTER
WRITING:
NON-TEXTUAL
CONTENT &
CTAS
38

39.
39
API
DESCRIPTION
ON INTERNAL
PORTALS
39

40.
40
Lot of APIs: orientation, gathering information, improve DX.
Internal
portals

41.
41
Few APIs: easy to generate, improve DX.
Internal
portals

42.
LET’S VOTE!
1. “API description”
2. “API overview”
3. “API summary”
4. Other
42

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.
Thank you!
Developer portal mailing list
bit.ly/devportals
44

45.
45