RT @DeliberateComp1: "How cognitive biases and ranking can foster an ineffective architecture and design" Don't miss out on… https://t.co/Njau4ATXn0
Ben Greenberg - The Journey of Our Documentation Platform to Station
API the Docs Virtual Event Series 2020 Recap
This talk was presented at API The Docs Virtual 2020 event series on 18 November. We are honored to share the video recording, slide deck, and talk summary below. Enjoy!
Visit the API The Docs 2020 recaps overview to explore all presentations this year.
If it is not documented, it is not done.
In 2017, the Vonage (formerly Nexmo) developer portal was a custom platform that based on Ruby on Rails, managed its content in Markdown. It was reliant on manual testing, and documentation and code were deeply intertwined: lived in the same repository. To write documentation with confidence, technical writers had to have knowledge of Ruby, Ruby on Rails, web development, and web applications in general.
A technical question, like Can you duplicate your portal? can lead to an adaptive solution. If a team has to maintain numerous unique portals, it has a negative impact on their emotional health. How to address these issues?
- Democratizing contribution, so people can focus on contribution in their expertise and interest area.
- Decreasing redundancy by increasing the number of sharable codes.
- Creating a style guide to help maintain the same look and style across multiple sites.
To build an adaptive solution a team needs to be resilient. They have to mind configurability and standardization, and also have to handle the emerging complexity. Frequent communication with stakeholders increases buy-in and improves iteration, also, the team can get valuable feedback early.
Documentation Portals Need Their Own Documentation
In 2020, 3 years later, the Vonage developer portal, now called Station, is a well-documented, open-source modular custom platform tool to generate numerous unique portals. It comes with a Markdown and an OpenAPI specification renderer that transforms the resources into fully functional web pages. Station has an automated testing suite to find broken links, spelling and code errors, and many more. The current solution supports internalization and manages the documentation and the code separately, so writers can focus solely on the content.