Slides from Write the Docs Ottawa Meet Up at Shopify HQ in Canada, June 24, 2019 We’ll walk through 5 scenarios and concrete ways of reaching a developer community for frictionless and increased engagement.

1. Content Strategies and Community
Engagement for Developer Portals
Emmelyn Wang lifewingmate
Write the Docs Ottawa

2. Content Strategies
and Community
Engagement for
Developer Portals
We’ll walk through 5
scenarios and concrete ways
of reaching a developer
community for frictionless
and increased engagement.
“Connection is why we’re here.” Brené Brown

3. 3 Maturity Levels
5 Developer Journeys
Level 1 No Developer Portal, Developer
Community, or API documentation
Developer Journey 1
Pre-launch stealth mode, technology in R&D, tech
docs as a means to support fundraising and
business development/partnership efforts
Developer Journey 2
Modern transformation of the Legacy API to a
Modern API (growing pains) | Tomb Raider
Iceberg model | What to expose?
Technical writer’s influence in API Design first
thinking and information architecture

4. Public
Private

5. 3 Maturity Levels
5 Developer Journeys
Level 2 Existing Developer Portal and
Community to Revamp, Outdated API docs
Developer Journey 3
Merger and Acquisition M&A, One organization
acquired another, combine similar APIs
Technical Documentation Team’s Magical Decoder
Ring of Sanity
Developer Journey 4
Moving the developer community from one platform
to another, transforming legacy docs to new formats
and matching technology
Staying platform agnostic requires heavy rework
without the spec as source

6. 3 Maturity Levels
5 Developer Journeys
Level 3 Healthy Developer Portal, Community,
and API Docs at Scale
Developer Journey 5
Developer Community = local and global
Code libraries and docs maintained for each
technology
The key for agility and rewarding participation
Proper incentivization
When to say no to hackathons
Engage and learn from the open source community

7. Additional Resource
https://static.sched.com/hosted_files/apistrat17/27/API%20Maturity.pdf

8. Competitive
Business
Landscape
Organizations of all sizes are now considering who owns
a full suite of technology offerings that they plan to
adopt as long-term advantage over competitors.
There are only a few independent DevPortal and API
Management vendors left in the space.
Relevance to Content Strategy?
Risk Assessments
Do you own your own content and life cycle?
Could you be using your competitor’s platform?
lifewingmate

9. The DevPortal is one of many kinds of platforms in an ecosystem

10. The DevPortal is one of many kinds of platforms in an ecosystem

11. Spectrum of DevPortal Options
Build
Choose Stack
Allocate
Resources
Buy
Requirements
Implement
lifewingmate

12. DevPortal
API Specification
Systems that
balance and
integrate a variety
of considerations:
Analytics, APIM,
Security, IAM
Experience
lifewingmate
Culture is the toughest piece, not the technology itself.
DevPortals with shared alignment are centered around the API specification.

13. How easy is it to find your swagger?

14. https://www.apimatic.io/transformer

15. https://www.apimatic.io/transformer

16. Discovery
How can internal
groups, customers,
partners, or third
parties try your API?
Offer both internal and
production sandboxes

17. Play
Give stakeholders
time to
experience the
API Value
01
Consider the
audience
02
Show the UI or
mock the
experience
03
Pair the
experience with
"what's under the
hood".
04

19. As expected, Sirius XM Holdings today
announced that it has completed its
acquisition of Pandora Media, making it “the
world’s largest audio entertainment
company,” according to the announcement.
After years of discussion, Sirius XM acquired
Pandora in a $3.5 billion deal last year.

20. Engage | Entry points and Feedback Loops
Human Touch,
Conversations, and
meaningful
interaction
Community,
Consistency, and
Confidence
Automation and self
service where/when it
makes sense

21. Measure
https://www.apiopscycles.com/measure
Typical APIOps Dashboards
➔ Business performance
➔ API Consumer dashboard
➔ API Provider dashboard
➔ Change events (deployments and infrastructure
changes) dashboard
➔ Alerts dashboard
Some example KPIs (Key Performance Indicators)
➔ Revenue (MRR) generated by APIs
➔ Other added value generated by APIs
◆ additional sales
◆ acquisitions
◆ TCV and other customer lifetime value metrics
◆ NPS
➔ API management recurring costs
➔ API management licensing and maintanance costs
➔ API management infrastructure costs
◆ cloud
◆ on-premise (if needed)
➔ APIOps costs
◆ development of new and existing APIs
◆ monitoring and maintaining APIs
◆ API runtime environment costs (cloud or on-premise)
Start with what you have:
What does your platform come with?

23. Measure
DIY Start
Download
MicroStrategy
Pull in data
sample
20+
visualizations
Take to the BI
team with your
sr. leadership

24. Measure
Bring your own
data as csv files
to start with to
show sample
visualizations

25. Measure
AI and Machine
Learning

26. The less friction you have, the
less engagement you must offer

28. Design developer journeys based on how a
developer chooses you.
Healthy Skepticism
The developer decides whether or not to
build using your API or technology.
➔ Reputation in the Developer Community
including successful track record
➔ Response time
➔ High availability for their use case
lifewingmate

29. Design developer journeys based on how a developer chooses
you.
Healthy Skepticism
The developer decides whether or not to build using your API
or technology.
➔ Security
➔ Dedicated resources and response type/time
➔ Relevant documentation
➔ Patterns and use cases for onboarding and to reduce the
complexity of the implementation
➔ Thoughtful architecture, design, to spec
➔ API Life cycle and maturity
lifewingmate

30. CONTENT STRATEGY FOR DEVPORTALS
Provide business and technology context
Business Development through Strategic Partnerships
Answer leadership’s understanding of the overall value: What do we get out of our investment?
Technology Adoption through driving efficient software development
Support a developer’s performance, reputation, and positive drive adoption of the technology
lifewingmate

31. THE CASE FOR DESIGN FIRST
CONTENT STRATEGY FLOW
Cost | Ease | Alignment
Software architecture is less
expensive and more
powerful when decided
upfront before affecting
downstream activity such as
building a software
application.
The same approach applies
to deciding core content
strategy before starting
downstream activity.
lifewingmate

32. User Story commit
OAS spec requires but
missing design oversight
codeBefore
After
API shipped!?
build and publish test
deploy artifact to test env
deployment done, let
devs know
verify deployment,
correctness, test MVAPI
deploy API to
prod
test, doc,
consume?
Inconsistencies across the specification
All downstream activities affected $$$
Stakeholders feedback not considered
Customizations and third party issues
business/PM
dev
devops
Consistency and automated API
Governance using the spec as source
Stakeholders feedback within design
Downstream activities accelerated for
faster API consumption, business
results
OAS spec
mock, test,
create
deployshare approved!
API shipped and delights users!

33. CONTENT STRATEGY
Provides a moderated and safe place to discuss ways for
developers to solve a technical problem.
Professional developers, especially your customers and partners,
may not want to add implementation specific details in a public
forum.
lifewingmate

34. CONTENT STRATEGY
Always provide clear expectations (what information and
interaction from where?) and community guidelines in channels of
communication.
Example of a clear Community Code of Conduct from the
Content+UX Slack Group
http://bit.ly/Content-UX-CoC-2
https://gist.github.com/theecrit/128c40f9c5959a1eb93292bf4028956d
lifewingmate

35. CONTENT STRATEGY
Continuity of Care is not just support ticket numbers linked
together in emails.
How is other information from your potential customers and
current customers and partners captured?
Decide where and when hardened content resulting from
answering similar recurring issues lives and is maintained.
It is quite possible that content strategy for DevPortals is more
about service.
lifewingmate

36. CONTENT STRATEGY
Map out where traffic is coming from and where it goes.
Crosslink where it makes sense.
lifewingmate
Technical Blog
Developer Newsletter
Syndication?
Target A
Target B
Target C

37. CONTENT STRATEGY
Map out where traffic is coming from and where it goes.
Crosslink between the two where it makes sense using SEO
optimized unique URLs. Be intentional about where you
drive traffic.
lifewingmate
Your Partnership
Page
Reseller Where to
Buy

38. Authentication
This collection uses the variable Bearer
{{oauth_token}} and content-type headers. When you
run the calls, you may need to set up global
authorization so that every call authenticates
successfully.
Code Samples
The source for these code samples is JSON according
to the OpenAPI version 2 specification.
CODE SAMPLE OPTIONS
Generated in this API documentation
▪ cURL
▪ jQuery
▪ Ruby
▪ Python Requests
▪ Node
▪ PHP
▪ Go
The "Generate Code Snippets" feature
within the native offers
▪ HTTP
▪ C (LibCurl)
▪ cURL
▪ C# (RestSharp)
▪ Go
▪ Java
▪ JavaScript
▪ NodeJS
▪ Objective-C (NSURL)
▪ OCaml (Cohttp)
▪ PHP
▪ Python
▪ Ruby (NET::Http)
▪ Shell
▪ Swift (NSURL)
https://vantagepoint2api.deltek.com/

39. Contextual clues The request body uses the collection body form so that the reference
descriptions show a bolded field name, data type, and the textual information about the field. In
the text section, required, and default values are bolded.
The major difference between the request and response bodies are the request descriptions
advising what valid values and where you can get data from (such as using another API call) and
what format the data must conform to for the request body to work.
EXAMPLE RESPONSE
The response descriptions are written in tables. See the entire table by hovering over the bottom
center of the response table a "Click to Expand" button pops up. Click on this button and the table
opens up in a module on its own page over the main documentation. Click the X on the top right of
the modal to go back to the API Reference.
Multiple versions
When viewing the code samples, if more than one example request/response pair exists, the
top Example Request will have a chevron arrow next to the name of the request. You can toggle
among the different code samples for that API call. You'll notice that the Example Response will
show a different success or error code which corresponds to the type of method (HTTP verb) used
on the resource. POST generally results in a 201 Created, for example.
https://vantagepoint2api.deltek.com/

40. A handshake is worth more than a click.
-Tim Falls, SendGrid

43. https://www.meetup.com/APIOps-Dallas/

45. JSON Validated by https://jsonlint.com/

46. lifewingmate
We’re Hiring Near You
Catalysts
API Solutions Architect
Instructional Designer

47. THANK YOU
Write the Docs,
You, Our Greater
Community
API the Docs and
the Speaker
Selection
Committee
Jason Harmon Kin Lane
Marilyn Rogers
Texas State
University MATC
Society for
Technical
Communication
Texas Chapters
WWCode
Women Who
Code Global and
DFW Chapter
lifewingmate
Confessions of a Content
Strategist | Aha Media Group

49. 2018 London | Emmelyn Wang
Content Strategy for DevPortals
Today’s Write the Docs Session is a continuation of the one delivered last Fall

50. What is the
Developer
building?
Curiosity
Emmelyn Wang

51. API Experience | Lead and Influence
1
Convey Value
Evangelize
internally and
externally
2
Design
Quality
Patterns
Support
3
Engineering
Community
Moderator
for relaunch
4
Developer
Community
Engagement
Manager
5
Test and
Document
6
Technical
Marketing
Director,
hardware,
software, and
IoT blend
7
Independent
API Strategist
8
Global
Content
Strategist
concepts and
results at
scale
Build and Consume Emmelyn Wang

52. Does your organization know which five
types of decision makers you are targeting?
Technical Leadership is the #1 resource for
non-technical business leaders to consult with as
trusted advisors – build your content strategy around
these advisors.
lifewingmate