Our Developer Site Gets a Major Update
By Charity Vargas
| Reading time 4 minutes
If you haven’t visited our developer website in a while, you will be pleased to see we have completed some major improvements.
Genability Developer Network (or GDN) is our website that helps software developers and teams get the most out of Genability’s products with technical documentation, examples, reference guides and How-To’s. Over the summer we put a lot of effort into a new version and it is jam packed with new content that helps you integrate quickly and get more from our offerings. It’s been live for a few weeks now and we’re really happy with the initial results. So what did we do?
Changes You Can See
The first thing you will notice is that the look and feel is different. We’ve made the layout more responsive. On a desktop it takes advantage of your whole window, and on a mobile device it adjusts nicely to fit your screen. The navigation is new, but should be familiar to those who use our Dash web application or our company website. Each content template has a newly designed layout that carefully considers its purpose. The font, colors and iconography are also new. In fact, we’ve updated nearly everything but the pink!
Cleaner Organization of its content
We also took the opportunity to refine the way we structure and categorize our content in the site. In particular, we wanted to do a better job of making it clear what the purpose of each section was. All content now falls into one of four main sections, each with a very specific purpose.
Quick Start - is the place to begin when you are new to our developer tools. Tutorials - pick your use case and walk through a step by step learning exercise. How To’s - dive deeper into specific, focused topics. API Reference - each API and data types requests and responses documented with reference materials and examples.
We want to make clear to the visitor that there is a logical “journey” through the site. Starting with the Quick Start, then moving on to the learning oriented Tutorials, followed by finding the API References (which are information oriented) and the How-To’s (which are problem oriented) for the specific task that prompted you to visit.
Lots of Improvements to the Actual Content
Most of the work has actually been in writing and editing the content itself. First off we have a significantly updated Quick Start Guide for those who are new to our APIs. We’ve also done quite a few edits to our two existing Tutorials, so they are more complete, and more focused on a logical end-to-end task flow. The How-To’s needed and got a lot of love (with more to come). Repetitive content and sections were removed and we put a particular focus on making sure a how-to article was comprehensive and on topic. There is more to do with the How-To section, but this version is a major improvement. Then the all important API Reference section was given an audit for completeness. It was in pretty good shape but it was none the less given some spit and polish.
Changes Behind the Scenes
For those of you technically inclined, we did sizable platform changes as well. The previous version of the site used a cloud CMS called Harmony. It lacks a robust version control mechanism, so for a while we’ve kept our content, written in markdown, in a Github repository. We used a simple, custom python script to convert it into HTML snippets. Copying and pasting these changes to Harmony got old a long time ago. So in this upgrade, we’ve migrated to Jekyll, with the site hosted as static HTML on Amazon S3. We use the wonderful Travis CI to automatically QA and run this process when triggered by a check-in for our development (a.k.a. staging) site. Travis CI also manages a Pull Request initiated workflow including reviewing and pushing changes to production in a “Continuous Delivery”-esque fashion. This system has been in place for a while now and we are happy that the frequency and quality of our updates to content have increased considerably. The whole company has been trained and is involved.
More Upgrades to GDN Planned
This was a big update, with changes to the underlying management and hosting, new theme and lots of content. It’s also a foundation for continued improvements such as:
Shared Postman Collection - We use Postman extensively at Genability, and will publish all the GDN site’s API calls as a collection Better Search - to help find the answers you are looking for. More Content - Our new processes help facilitate this with easy and safe promotions.
Give Feedback Get Messenger Bag
We often hear from folks “we love the pink” or “your APIs are really well documented”. While we love the positive feedback, we are always striving to give our customers the best information. So with this in mind we challenge you to give us some feedback or point something out that is missing or unclear. Give us a suggestion that we use to improve our customer experience and we will give you a free Genability messenger bag! So please do email in your feedback.
Also in Products
By Ruben Garcia | Jul 3, 2017
By Jenny Trinh | Apr 4, 2017
By Tarpan Dixit | Oct 5, 2016
By Jason Riley | Aug 1, 2016