Arrival: The Journey of our Documentation Platform to Station

A presentation at API The Docs Virtual in November 2020 in by Ben Greenberg

Slide 1

Slide 1

Arrival: The Journey of our Documentation Platform to Station PRESENTED BY: Ben Greenberg @rabbigreenberg

Slide 2

Slide 2

We start with a simple truth: @rabbigreenberg 2

Slide 3

Slide 3

If it is not documented, it is not done. @rabbigreenberg 3

Slide 4

Slide 4

2017 @rabbigreenberg 4

Slide 5

Slide 5

@rabbigreenberg 5

Slide 6

Slide 6

The Journey Begins With: • Custom Platform - Not out of the box • Ruby on Rails - Well trodden technical path, lots of community support • Markdown Content - Lower threshold to contribution, standard formatting • Focus on Manual Testing - More reliant on human bug catching • Documentation & Code Intertwined @rabbigreenberg 6

Slide 7

Slide 7

2020 @rabbigreenberg 7

Slide 8

Slide 8

3 Years Later: • Custom Platform Tool - One tool, Station, to generate numerous unique portals • Markdown Renderer - Lower threshold to contribution with ability to create custom formatting with no code • OpenAPI Renderer - API docs universally rendered with standardized specification • Automated Testing Suite - Automating the things that can be automated so people can do the things automation cannot • Internationalization - Thinking beyond the English speaking world • Documentation & Code Separated @rabbigreenberg 8

Slide 9

Slide 9

The Station Tooling Ecosystem @rabbigreenberg 9

Slide 10

Slide 10

Small Tools To Support Big Goals NEXMO-MARKDOWN-RENDERER Transform markdown into fully rendered web pages PRESENTATION TITLE NEXMO-OAS-RENDERER Present OpenAPI specifications inside Station CUSTOM GITHUB ACTIONS Run testing suite, check for spelling, find broken links, and a lot moe @rabbigreenberg 10

Slide 11

Slide 11

Each small tool is a single-purpose modularized component of Station @rabbigreenberg 11

Slide 12

Slide 12

Why Did We Build Station? @rabbigreenberg 12

Slide 13

Slide 13

It Started With A Question… @rabbigreenberg 13

Slide 14

Slide 14

Can You Duplicate That For Us? @rabbigreenberg 14

Slide 15

Slide 15

Yes* *But, Let’s Do Something Else @rabbigreenberg 15

Slide 16

Slide 16

A Technical Question Can Lead To An Adaptive Solution @rabbigreenberg 16

Slide 17

Slide 17

Impact of Number of Unique Portals To Emotional Health There is an inverse relationship between the number of portals and emotional health Note: This table comes only from my imagination, and does not represent empirically derived information. @rabbigreenberg 17

Slide 18

Slide 18

What Does Station Solve? @rabbigreenberg 18

Slide 19

Slide 19

Democratizing Contribution When you take care of the foundations… People can focus on contributing in their expertise and interest area @rabbigreenberg 19

Slide 20

Slide 20

Writing Docs Is Its Own Valuable Expertise @rabbigreenberg 20

Slide 21

Slide 21

Engineering 💙 Happiness D.R.Y. (Do Not Repeat Yourself) Multiple Sites With Overlapping Needs, Use Cases and Functionality? Shared Code Increases Developer Satisfaction @rabbigreenberg 21

Slide 22

Slide 22

Maintaining the same look and style across multiple sites is HARD. @rabbigreenberg 22

Slide 23

Slide 23

What Were The Challenges? @rabbigreenberg 23

Slide 24

Slide 24

Encouraging Patience for Adaptive Solution Building @rabbigreenberg 24

Slide 25

Slide 25

A DIALECTIC TENSION: Configurability and Standardization @rabbigreenberg 25

Slide 26

Slide 26

A DIALECTIC TENSION: Configurability and Complexity @rabbigreenberg 26

Slide 27

Slide 27

How Did We Address Them? @rabbigreenberg 27

Slide 28

Slide 28

Communicate Communicate Communicate … and then communicate again @rabbigreenberg 28

Slide 29

Slide 29

Configurability Checklist • Common across portals? • Level of complexity? • Reusable? • Shared business style? • Specific request? @rabbigreenberg 29

Slide 30

Slide 30

@rabbigreenberg 30

Slide 31

Slide 31

@rabbigreenberg 31

Slide 32

Slide 32

Exceptions as Guides for Configuration The more ambiguous the error, the more frustrating the experience @rabbigreenberg 32

Slide 33

Slide 33

What Are Some Key Takeaways? @rabbigreenberg 33

Slide 34

Slide 34

Where You Start Is Not Where You Will End @rabbigreenberg 34

Slide 35

Slide 35

Separation of Code and Prose Respects Each Contributor For Their Unique Expertise @rabbigreenberg 35

Slide 36

Slide 36

Communication Increases Buy-In And Improves Iteration @rabbigreenberg 36

Slide 37

Slide 37

Documentation Portals Need Their Own Documentation @rabbigreenberg 37

Slide 38

Slide 38

Public Documentation Bootstrap Doc Portal @rabbigreenberg 38

Slide 39

Slide 39

What’s Next? @rabbigreenberg 39

Slide 40

Slide 40

Know Thyself The greater the user personalization, the greater the impact. @rabbigreenberg 40

Slide 41

Slide 41

Resources: • Station on GitHub: https://github.com/Nexmo/station • Station on Rubygems: https://rubygems.org/gems/station • Station Documentation: https://nexmo.github.io/station/ • Bootstrap Portal Project: https://github.com/nexmo-community/minim al-doc-product • Vonage API Developer Portal: https://developer.vonage.com • Vonage Business Communications Portal: https://developer.uc.vonage.com/ @rabbigreenberg 41

Slide 42

Slide 42

Thank you. Questions? Comments? Please Be In Touch! @rabbigreenberg || ben.greenberg@vonage.com @rabbigreenberg 42