A presentation at API The Docs Virtual by Ben Greenberg
Arrival: The Journey of our Documentation Platform to Station PRESENTED BY: Ben Greenberg @rabbigreenberg
We start with a simple truth: @rabbigreenberg 2
If it is not documented, it is not done. @rabbigreenberg 3
2017 @rabbigreenberg 4
@rabbigreenberg 5
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
2020 @rabbigreenberg 7
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
The Station Tooling Ecosystem @rabbigreenberg 9
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
Each small tool is a single-purpose modularized component of Station @rabbigreenberg 11
Why Did We Build Station? @rabbigreenberg 12
It Started With A Question… @rabbigreenberg 13
Can You Duplicate That For Us? @rabbigreenberg 14
Yes* *But, Let’s Do Something Else @rabbigreenberg 15
A Technical Question Can Lead To An Adaptive Solution @rabbigreenberg 16
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
What Does Station Solve? @rabbigreenberg 18
Democratizing Contribution When you take care of the foundations… People can focus on contributing in their expertise and interest area @rabbigreenberg 19
Writing Docs Is Its Own Valuable Expertise @rabbigreenberg 20
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
Maintaining the same look and style across multiple sites is HARD. @rabbigreenberg 22
What Were The Challenges? @rabbigreenberg 23
Encouraging Patience for Adaptive Solution Building @rabbigreenberg 24
A DIALECTIC TENSION: Configurability and Standardization @rabbigreenberg 25
A DIALECTIC TENSION: Configurability and Complexity @rabbigreenberg 26
How Did We Address Them? @rabbigreenberg 27
Communicate Communicate Communicate … and then communicate again @rabbigreenberg 28
Configurability Checklist • Common across portals? • Level of complexity? • Reusable? • Shared business style? • Specific request? @rabbigreenberg 29
@rabbigreenberg 30
@rabbigreenberg 31
Exceptions as Guides for Configuration The more ambiguous the error, the more frustrating the experience @rabbigreenberg 32
What Are Some Key Takeaways? @rabbigreenberg 33
Where You Start Is Not Where You Will End @rabbigreenberg 34
Separation of Code and Prose Respects Each Contributor For Their Unique Expertise @rabbigreenberg 35
Communication Increases Buy-In And Improves Iteration @rabbigreenberg 36
Documentation Portals Need Their Own Documentation @rabbigreenberg 37
Public Documentation Bootstrap Doc Portal @rabbigreenberg 38
What’s Next? @rabbigreenberg 39
Know Thyself The greater the user personalization, the greater the impact. @rabbigreenberg 40
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
Thank you. Questions? Comments? Please Be In Touch! @rabbigreenberg || ben.greenberg@vonage.com @rabbigreenberg 42
Vonage APIs is a complex and feature rich suite of API products and tooling. Each product is a microcosm of complexity and inextricably linked to others in the suite. How do you choose the technology for a documentation platform for both current needs and those that have not yet been anticipated?
That was the challenge in 2017 when we launched our first iteration of the platform. We chose to build our own custom documentation site rather than adopt an off the shelf solution, because we always wanted to retain the flexibility to say “yes” to any evolving change as the business needs grew and evolved. That same desire led us to radically redesign our single-purpose documentation platform as a global solution for all our documentation needs both now and in the future. We call this new platform Station.
Previously, contributing content to our documentation site had more in common with software development than writing. It was time-consuming, error-prone and complex. But now, Station separates the content from the platform that renders it. Anyone can create and deliver content without needing to know the underlying technology stack.
Why did we embark on this journey? What problems were we hoping to solve? What benefits did it yield? In this talk we will cover the business needs that led us to transition our platform into Station and why we chose the path we did. We will walk through the pain points in the process, the key takeaways we gleaned and examine the benefits it has delivered thus far.
for free. You
can too.