RingCentral's Code Sample Generator

The heart of every successful developer platform is robust documentation published in a variety of forms — from getting started guides to tutorials designed for developers of all skill levels, not to mention the ubiquitous API Reference. Regardless of the form the documentation comes in, they all have one fundamental need in common: code samples.

You might also like:  Work With RingCentral APIs

At RingCentral, we struggled with creating and maintaining code samples scattered throughout our ecosystem. Coming together, we identified the following challenges in achieving our ideal of 100% code sample coverage for every endpoint and every supported language:

1. Maintaining Consistency — our documentation is often written by multiple people. Each of us has our own unique coding style, resulting in a lot of variabilities not only in an over-arching coding style/convention but even between code samples for a single endpoint.
2. Language Bias — most of us at RingCentral are comfortable with many programming languages, but none of us are fluent/expert in them all. As a result, we noticed our documentation often reflected certain language biases that left some of our developers out in the cold.
3. Coverage/Completeness — under pressure to ship products, we sometimes found ourselves in the unfortunate situation in which we had to cut scope from a release — and we found that documentation was especially vulnerable to being compromised. Cumulatively, this resulted in documentation that lacked the code samples we initially wanted and causing the team to fall short of our goal of making sure every endpoint had all accompanying code samples.
4. Quality — while our SDKs and libraries have unit tests accompanying them, we lacked a scalable system to find, extract and test code samples sprinkled about our documentation ecosystem. Over time, this resulted in code samples breaking without anyone knowing - or at least not knowing until a customer alerted us.
5. Style and Personality — finally, we observed that the code samples initially created from our swagger specification lacked authenticity and any sense of our brand, and those code samples were nearly impossible to customize.

Our Solution

We first turned to documentation frameworks to see how they measured up with regards to helping us to solve the challenges above. Most of these frameworks operate by inputting a swagger specification and then generating an interactive API reference of some kind.

We quickly came to the consensus to build our own tool for one simple reason: these frameworks are designed as standalone documentation systems, are not designed around the goal to make re-using code samples across all forms of documentation easier.

Optimized for Re-use

We wanted our system to output code samples that could not only be easily used in an API Reference, but in our Developer Guide, and in our SDKs. This would help us ensure that developers always be presented with code samples in a consistent style, that all adhere to the same standards regardless of where they happen to view a code sample.

The value of re-use, however, is not restricted to re-use within the context of documentation alone. One problem we need to solve was a scalable way for us to test our code samples in the future. Such a system would require code samples that would benefit from code samples that lived on the filesystem and that could be bootstrapped by a testing framework. Not only would this help us ensure the integrity of our documentation, but it would also provide a more robust way to test all of our SDKs in one fell swoop.

Templatized

For the longest time, our documentation included unintentional language biases because those primarily responsible for documentation were most fluent and comfortable writing Javascript and Python. If we wanted to support other languages, we often relied on a handful of resources outside our immediate group to help us produce the samples we needed — resources that weren't always available at the time.

As a result, our coverage across languages important to our customers, like Java and C#, was relatively neglected. It was, in fact, this short-coming that served as the catalyst for our larger inquiry and project to improve our code samples.

To address this, we designed our code sample generation system around output templates for each major programming language we wanted to support. This enabled us to engage language experts within our company in a more scalable way. Rather than having to go back to the well time and time again asking them for this new code sample or that one, we worked with them on defining the ideal format we should utilize for all code samples in their language — and let the framework do the hard work for them.

How it Works

The RingCentral Sample Code Generator is currently designed around our own process outlined below.

1. Download Dependencies

Fundamental to how the Sample Code Generator works is a swagger specification that defines all the inputs and outputs of an API. Therefore, step one of the generation process is to download the latest version of the swagger spec for which code samples will be generated.

2. Generate Code

Next, using the swagger spec, sample code is generated for each endpoint in each of the languages supported via a set of EJS templates shipped with the framework. We currently support: Javascript, C#, PHP, Python, and Java.

3. Look for Overrides

We encountered a few edge cases for which designing templates would have been slightly impractical. We decided that for these few edge cases, it would be easier for us in the short-term to create sample code manually. We wanted these hand-crafted code samples to take precedence over what the framework would generate on its own. So the framework searches a directory tree for "code sample overrides" — if one is found, the framework will output that instead.

Granted, this is a hack, but a useful hack when one does not have the time to toil with templates and spec files to achieve a relatively obscure output or to deal with some SDK idiosyncrasy.

4. Output Files

We wanted our code samples to be navigable in their raw format directly by developers, so the final step is to output a directory tree containing all the code samples the framework generated. We chose to publish these code samples to a GitHub repository, which incidentally made it easier for others to check out and incorporate it into their documentation systems.

Our system also generates additional artifacts that incorporate these code samples — including auto-generated documentation files that can be distributed with each of our SDKs. Other files can be output as well — all driven by the templates you create.

Getting Started

We hope others within the broader developer community, especially platforms that sympathize with many of the challenges we faced, find value in the framework and solution we developed. To get started, here are some resources you may find useful:

• RingCentral Code Sample Github Repository
• RingCentral Code Sample Generator

Further Reading

Messaging APIs of RingCentral

Build and Graduate Your App in RingCentral