apidays LIVE Paris 2021 - APIs and the Future of Software December 7, 8 & 9, 2021 The content devportal: Who writes the Docs? Laura Vass, Co-Founder of Pronovix, the DevPortal Awards & API The Docs at Pronovix

1. The content DevPortal:
Who writes the Docs?
Laura Vass
co-founder @
PRONOVIX, The DevPortal Awards, API The Docs

2. Explore and share
developer portal best practices
devportalawards.org apithedocs.org

3. Developer eXperience centered Digital Transformation
3

4. 4
Setting: You have an API. You publish it on your developer
portal, at least the first iteration. Great.
Then you realize: 50% of creating an API is designing it. The
other 90% is writing and maintaining its full documentation.
The conflict point

5. 5
1. Scope
2. Ownership
3. Tools
4. Processes
Maintenance requires clarity:

6. New York
JULY
Australia
SEPTEMBER
Singapore
APRIL
Helsinki & North
MARCH
Paris
DECEMBER
London
OCTOBER
Jakarta
FEBRUARY
Hong Kong
AUGUST
JUNE
India
MAY
Check out our API Conferences here
50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees,
300k+ online community
Want to talk at one of our conferences?
Apply to speak here

7. Scope
What, and whom is a devportal for? What docs do we need there?
1
6

8. What is a developer portal?
7

9. Developer Portals
are a
Communication Hub
for all
API stakeholders
8

10. Minimal Viable
Docs
● Home page,
Product pages
● Registration,
API / Key Access
● API References,
Try It Out
● Contact, FAQ
9
Docs to implement
& integrate
Value
proposition
Docs to get
started
Help

11. 10
More Docs
● business info
● pricing
● case studies
● legal: T&C, policies
● regional info
● changelog
● status
● release notes
● external sources
● community news
● blog
● tutorials
● concepts
● go live guides
● SDKs
● feedback forms
....

12. Ownership
Which teams are involved and how? Who writes the docs?
2
11

13. “ Who writes the docs?
Who owns the devportal?
● Me (When?)
● Them (Who?)
● Everyone (How??)
12

14. Modeling operational maturity
Devportal is run as a:
● Project
● Product
● Critical business infrastructure
13

15. ● Everyone is somehow involved. We have technical people,
who are responsible for writing the documentation and
maintaining the technical solution, and then we have the
marketing/operations branch responsible for sharing the
content and promoting the developer portal.
● We do not have business-only authors for the developer portal
and I still quietly hope that we will never need them. We have
an internal guide on how to run the developer portal locally so
that everyone can edit content.
14

16. ● Engineering is responsible for building and maintaining the
platform and all associated content.
● Content is created and managed using a SSG via the portal's
Github repo, and the site is built via CI/CD. This workflow
means it is difficult for business authors to create and manage
content themselves, so we are planning to build a CMS
integration to make this possible.
15

17. ● Everyone in the team, partner, and user communities can
contribute, while our documentation lead drives all docs
related processes through a carefully considered strategy.
● Less technical users sometimes provide use cases, where we
help them by providing a use case template, and we go
through the review and editing if that makes the experience
more comfortable for them.
16

18. Documentation is created with several review circles in place:
● Product analyst (and other SMEs) check the material for
factual accuracy
● Technical writers review content structure, style guide
compliance, or specific terms
● Copywriter checking the docs to make sure it is easy to read
● Translation team
● Testing process. It involves both the technical writer who
created the article, and a QA engineer.
17
”

19. ● Content is generally drafted first by an SME such as a
developer or PM, then edited by a member of the DevRel
team.
● Depending on how extensive the content is this editing
process may be simple proofreading or involve a lot of back
and forth.
● For some surface areas, a member of a team such as legal or
security may also be required to review the change,
● and for API changes, a member of the API standards
committee is required to review it.
● For visual asset, we will file a ticket for the Design team to
assist and/or meet with them during their weekly office hours.
18
”

20. ● We have a dedicated cross-functional team
including Engineering, Product, Design, and Support
that owns the portal,
● as well as another dedicated cross functional team
with Developer Relations, Engineering and Design
that owns the docs.
● We also take input from other teams such Sales and
Support.
19
”

21. ● One multidisciplinary team acts as a central hub:
professionals in documentation, operations and support,
portfolio management, community building, user experience,
and development. The teams that develop APIs provide
content, both business and technical, example use cases, and
blogs for promotion.
● Next to that, multiple teams enable the API creation and
management processes. These include our security team,
both internal and external gateway teams, and the team
responsible for ensuring all our APIs meet the industry
standards.
20
”

22. 21
But in the
beginning...?
What can each person, where
they are right now, do?
Do you know what drives them,
and do they know it?

23. 22
Documentation issues (often) start
at the creation of the thing itself that
needs to be documented.

24. Pain points could be:
● Poor discoverability -» redundant work & friction
● Domain language ambiguity -» confusion & errors
● Lack of design standards -» inconsistent DX
● Lack of documentation -» wasteful onboarding
● Fragmented, complex authentication -» access frustration
23

25. What cannot be automated:
empathy
● Documentation is also a thinking tool, not just marketing.
● The very important gets obfuscated by technical details.
● Human empathy to explain what something is.
● For APIs, the DATA is what matters, and what you can do with that
data.
24

26. “ Whatever extracts order from
chaos is properly done if
it's done in truth.
paraphrased from Jordan Peterson
25

27. New York
JULY
Australia
SEPTEMBER
Singapore
APRIL
Helsinki & North
MARCH
Paris
DECEMBER
London
OCTOBER
Jakarta
FEBRUARY
Hong Kong
AUGUST
JUNE
India
MAY
Check out our API Conferences here
50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees,
300k+ online community
Want to talk at one of our conferences?
Apply to speak here

28. 26
Thank you!
info@pronovix.com
linkedin.com/in/lauravass
https:/
/pronovix.com https:/
/devportalawards.org https:/
/apithedocs.org