1.
Leaping Forward
Finding The Future Of Your API Docs

2.
FUN!

3.
Why leap forward?

4.
For API platforms,
developer docs are essential!

5.
PlatformComplexity
Time
Required documentation

6.
PlatformComplexity
Time
Required documentation
Productivity

7.
PlatformComplexity
Time
Required
documentation(New hires)
Productivity

8.
PlatformComplexity
Time
Required
documentation
Productivity
(New hires)
Actual documentation

9.
Oakland, CA
London, UK
Aaron Verber
Product Manager,
Developer Relations

10.
What goes in your
“leap forward” toolkit?

11.
History

12.
In 2016,
MARQETA
became the first issuer-processor
to publicly document its payments API

13.
2016
One writer in our marketing CMS

14.
2018
Four writers in our marketing CMS

15.
Know the history.
● Ask who wrote the original docs.
● Ask who built the original tools.
● Keep a record of the docs history.
● Use tools like archive.org to take a look back.

16.
Signs of trouble

17.
2020 Product Roadmap

18.
2016 Docs Pipeline

19.
Do you:
● Create fragile processes to cover tool gaps?
● Worry about overwriting unpublished work?
● Avoid certain docs because the tool is too difficult?
● Prefer writing docs outside your tool?

20.
Watch for signs of trouble.
● Avoid bad processes meant to cover tool gaps.
● Avoid needing to work outside your tool.
● Track unintended or undesirable outcomes.

21.
Pain points

22.
No collaboration
No version control
No review tools
Limited page size
Limited organization options

23.
What resources do our developers need?
PaymentsCompetency
Technical Competency
★
Required competency for success
Your awesome
platform goes here
Your developers
(usually)
start here

24.
What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)

25.
What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)
DevGuides(2017)

26.
What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)
DevGuides(2017)
Tutorials (2018)

27.
What resources do our developers need?
PaymentsCompetency
Technical Competency
★
API Reference (2016)
DevGuides(2017)
Tutorials (2018)
PaymentsBasics
SDKs (2019)

28.
Simple but powerful authoring
Move docs closer to the code
Prepare for automated tools
Keep the source portable
An existing ecosystem

29.
Go beyond pain points.
● What could you do with a new tool? Dream big!
● Create a shared taxonomy describing your docs.
● Communicate!
● Demonstrate the added value with a prototype.

30.
Prototypes

31.
We chose Gatsby + AsciiDoc.

32.
We chose Gatsby + AsciiDoc.
(Eventually.)

33.
2017 Hack Week Prototype

34.
2018 AsciiDoc + Hugo Prototype

35.
Why AsciiDoc?

36.
Possibility space!

37.
Humans can read the source.#1

38.
Humans can read the source.
#2
#1
There’s a healthy ecosystem.

39.
Gatsby
A static-site generator
AsciiDoctor
A text processor
and plugin for Gatsby

40.
Gatsby
A static-site generator
AsciiDoctor
A text processor
and plugin for Gatsby

41.
GitHub
A git host for
version control
Visual Studio Code
A text editor

42.
GitHub
A git host for
version control
Visual Studio Code
A text editor

43.
Humans can read the source.
#2
#1
#3
There’s a healthy ecosystem.
It can live near your code.

44.
Humans can read the source.
#2
#1
#3
#4
There’s a healthy ecosystem.
It can live near your code.
It’s convertible and portable.

45.
Humans can read the source.
#2
#1
#3
#4
#5
There’s a healthy ecosystem.
It can live near your code.
It’s convertible and portable.
It’s free and you own your content.

46.
Build your own prototype.
● Limit risk by putting your plan into action early.
● Give yourself time to find and reject the wrong tools.
● Keep in mind any third-party content policies.
● Use tools like Stackbit and Netlify to try SSGs.

47.
Practice

48.
Use the transition to practice.
● Document your tool using your tool.
● Start a dedicated Slack channel.
● Test your new publishing process.
● Run user testing, too!

49.
The Future

50.
Content management system
+ Easy to use
- Vendor-based ($$$)
- Monolithic and bulky

51.
AsciiDoc-based toolchain
+ Extensible & testable
+ Standards-based
- Assembly required
Content management system
+ Easy to use
- Vendor-based ($$$)
- Monolithic and bulky
is here!
Gatsby
Static site
generator
AsciiDoc
Markup
syntax
GitHub
Version
control
Drone
CI/CD

52.
API spec-based toolchain
+ Automates multiple outputs
+ Source of truth = code = docs
- Organizational buy-in required
AsciiDoc-based toolchain
+ Extensible & testable
+ Standards-based
- Assembly required
Content management system
+ Easy to use
- Vendor-based ($$$)
- Monolithic and bulky
is here!
OpenAPI
API spec
Your API
Docs + code samples
SDKs, Postman, etc.
Gatsby
Static site
generator
AsciiDoc
Markup
syntax
GitHub
Version
control
Drone
CI/CD

53.
Be thoughtful about the
long-term writing experience
and information architecture.

54.
NOW
COOL
TOOL
BETTER
TOOL
...can you leverage this?If you over-develop
this...

55.
Plan for the future.
● Choose tools that can grow and adapt with you.
● Don’t over-invest in any one tool or format.
● Build in phases toward your end goal.
● Keep dreaming up the next big improvements!

56.
Your giant leap toolkit
1. Know the history of your docs site, tool, and team.
2. Track any signs that you’re digging yourself into a hole.
3. Go beyond pain points to show added value.
4. Build your own prototype.
5. Use the transition to practice.
6. Plan for the future to make your next leap easier.

57.
Thanks!
@aaronverber
@marqeta