In Context

The next-generation communications blog from Nexmo

< Back

Introducing Nexmo Developer

July 25, 2017 Published by

Nexmo Developer is the new home for our documentation, API references, community content and resources. Our team has been working hard to improve our developer experience: whether you’re new to Nexmo APIs or a well accustomed with our platform and tooling, the new Nexmo Developer site makes life easier for you to find what you need to work with our platform.

We will continue to iteratively improve on Nexmo Developer and provide new and innovative ways to help you implement Nexmo APIs into your products quickly, confidently and efficiently.

A bit of history

Having great tooling is incredibly important for being agile, iterative and innovative. Prior to Nexmo Developer, the documentation for Nexmo APIs was at docs.nexmo.com, a site that has served its purpose well over the last four years.

As we looked to evolve our documentation beyond just guides, our mostly statically-generated site documentation site didn’t seem like the best option for moving forward with. We needed something to accelerate us, have the power to be dynamic but retain the simplicity that we’ve come to love from file-based static site generators.

Our Goals

In January 2017, we started planning out an information architecture that would make content in Nexmo Developer easy and intuitive to find, and to provide consistent content across our products.

We arranged distinct content types such as Documentation, Tutorials and API Reference in our top navigation providing quick and direct access to the most appropriate content for your stage of development.

We then arranged our documentation to be organised by product (Messaging, Voice, Verify and Number Insight), each of which contains the following sections:

  • Overview – A quick look at what the product is and its capabilities including an example quick start implementation
  • Guides – In depth articles about specific product features
  • Building Blocks – Quick access code samples to help you construct your programmable communications apps
  • Tutorials – Step-by-step tutorials to help you build common communications use cases
  • Reference – The resources, parameters and payload examples

Alongside this we created a collection of values that would provide a clear direction for us going forward:

Simple

Nexmo Developer should serve as the clearest example of what our products are and how to implement them. Documentation and examples should contain no more than the minimum amount of information the developer needs to understand to implement the product.

Developer centric

Nexmo Developer should be built with developers in mind. The site should be designed to be clear, concise, technical and to the point. Furthermore, effort should be focused on what is really important for the developer. Eliminating inaccuracies or ambiguities should remain our priority ahead of superficial changes.

Easy to navigate and consistent

The information architecture of Nexmo Developer should be designed to allow developers to find the most appropriate information for their stage of development as easily as possible.

By enforcing a clear and consistent structure throughout the documentation, content will become easier to find and quickly retrievable at a later date.

A style guide should be maintained outlining the structure in more detail, the requirements for guides and the tone of voice for the Nexmo Developer copy.

Accessible

Accessibility is really important and goes beyond semantic machine readable markup and ARIA roles. Accessibility is also about catering for developers with different programming language preferences and enabling developers of a diverse range of technical expertise. The content that we create should be driven by this: providing resources appropriate for all ranges of skill level at all stages of a product lifecycle.

Shareable

Content should be linkable and simple to share. Nexmo Developer is the canonical source for our platform documentation and the ability to share anchored links over support platforms such as our knowledgebase and Stack Overflow will deter copying of content that might become outdated.

Beautiful

Nexmo Developer design should be optimised for readability, clarity and scannability. The elements that are styled should be done with care, consistency and simplicity in mind.

Beauty should be a consideration when designing and used to reinforce the craftsmanship of our product. It can also be used as a mechanism for enhancing more in-depth topics and can be used when making components visually intuitive, for example making code blocks resemble a modern editor.

Canonical and Versioned

At the time of writing, our legacy documentation exists at docs.nexmo.com

It is important not to break a resource that a developer is using and that we maintain support for all URLs that other resources are using.

Significant future changes should also be versioned, especially if a product or service is deprecated or changes significantly.

Collaborative

The tooling we build should empower other people throughout the business as well as our customers to contribute to Nexmo Developer easily. Documentation on how to contribute should be provided in order to both encourage and enable contribution, whilst maintaining consistency.

We’ve made great progress towards making these goals a reality and will continue to iterate and improve on our platform and share our findings along the way. We’d love to hear your feedback so please feel free to open an issue if you’ve got any suggestions on how we can improve Nexmo Developer.

What we’ve done so far

We’ve got a lot planned for the future of our content, but given our breadth of products, it was important to take what we had already and make it much more accessible, readable and discoverable.

Alongside the guides that we transitioned we created new overview pages for all of our products making it easy to understand their capabilities and to help developers to find the information they needed as easily as possible. We also introduced ‘building blocks’ as a quick reference to common practical implementations. We hope you’ll find these as useful resources during discovery and development phases.

We moved API references into its own section, and by adding a side navigation, it’s easier than ever to find the content you need and keep track of where you are when you are context shifting between Nexmo Developer and your codebase.

We’ve added all new search support powered by Algolia helping you find content more quickly across Nexmo Developer and our Knowledgebase.

Lastly, we’ve created a new community section with support for videos, and information on the events where you’ll find our team attending, sponsoring or speaking. We’re excited to grow this to be a hub of community driven content in the future.

From a technical standpoint, we made Nexmo Developer simpler to contribute to by providing contributing guidelines, by making our platform more predictable and by simplifying many aspects of the Markdown source documents.

Technical approach

We built Nexmo Developer as an open-source platform, using a mix of Ruby on Rails, HTML, JavaScript (ES7 + Webpack), Sass and a document parser that extends Markdown with extra functionality useful for writing technical content. All of the tooling and documentation is available for you to contribute to or remix for your own project.

The documentation content is file-based, making it easy for anybody to contribute even within GitHub’s own code editor with Markdown support. Alternatively, you can clone Nexmo Developer locally and run it in your own development environment; we even have Docker support to make setup easy and self-contained.

Why Open-source?

Nexmo Developer was built with collaboration in mind. Anybody should feel welcome to contribute to our platform or content. We’ve created a tool that enables technical writers to easily and simply enhance documentation with supporting content such as tabbed code examples, UML sequence diagrams and much more.

Throughout our research and development we’ve spoken to various other technical writers and through these discussions believe we’ve built a platform with a strong foundation with a healthy balance of simplicity and power. We wanted to share this tool with others, to give back to the incredible open-source community and to enable anybody to contribute however they think they could add value.

You can find Nexmo Developer on GitHub

What next?

In the short term, we’ll be reviewing our content and improving our code examples to be more consistent and to use our Libraries. We’ll shortly be adding search support helping you find content more quickly across Nexmo Developer and our Knowledgebase.

In the future, we’ll be looking to revise our API Reference and have it powered by OpenAPI Specification to be consistent, simpler to navigate and easier read. We’ve also got a lot of ideas about personalising documentation examples and adding interactivity to our tooling where appropriate to enrich our learning resources.

Conclusion

We’ve come a long way, but we’ve got much to do and improve. We hope that the steps we’ve made will have a positive impact on you and your teams’ productivity when integrating with Nexmo.

As always we welcome feedback. Please let us know using the feedback tool (👍👎) at the bottom of each guide or file an issue on GitHub.

Tags: ,

Categorised in: , ,

This post was written by