We've launched Emsi's API documentation site!
Over time as my role has changed, work at Emsi looks less like writing code and more like leading and coordinating the coding of others. This was a fun opportunity to do both and roll up my own sleeves for some frontend coding!
One of the challenges Emsi has faced while developing our API documentation is that multiple teams contribute public-facing APIs, and teams have historically used different tools and tech to do so. In the past each team owned its own documentation experience, which resulted in a fragmentation. With the launch of this documentation site we're taking a step toward unification.
To address this challenge of fragmentation but maximize team autonomy, the docs site architecture had to satisfy 3 requirements:
- Bring all documentation into one place. Mission accomplished with a new site.
- Ingest documentation in multiple formats. To accomplish this, the docs site accepts an extension of markdown with special formatting for generating API examples (httpsnippet works wonders). Markdown is a common denominator that various teams can write directly or easily generate automatically from their API documentation format of choice.
- Allow teams to deploy documentation changes independently. Emsi APIs host their own documentation, and the docs site pulls it together on the fly. This allows API teams to own their own deployment fully, including documentation.
You can check out the video walkthrough of the site below.