One of the most important but often overlooked aspects of building a strong developers’ community is DOCUMENTATION. Therefore it is always a good practice to see how the big players are already handling such issues.

In this article, I will give you a short overview of how Foursquare has managed to successfully deal with this stuff.

After reviewing the existing documentation they’ve launched an entirely new version of developer.foursquare.com, full of features “to help developers get started and explore their location intelligence tools".

There are two areas I want to cover in this short overview: Infrastructure and Feature Improvements.

INFRASTRUCTURE IMPROVEMENTS

✔ Content management — Jekyll framework is used to convert markdown documents into a reusable documentation platform while custom plugins help with faster and easier documentation update

✔ Deployment —  there is a script used for building an image from Dockerfile and exposing Foursquare’s pages via Nginx web server

✔ Automation —  to decouple docs and allow fast live updates, buildings are picked up automatically via Travis-Ci

FEATURE IMPROVEMENTS

✔ Searching —  with the use of ElasticSearch Foursquare built a search engine reindexing with every docs site update. The search engine enables devs to find specific keywords, endpoints or error responses. What’s even more, the company has created an API allowing seamless integration to 3rd parties. Hence, integrating directly into IDEs like Android Studio and Xcode is easy

✔ Endpoint Pages—  due to the fact that endpoint pages have API responses, which is absolutely great, developers can easily see the expected output from endpoints

✔ Sample Apps & Libraries  — there have appeared additional Sample Apps. Thanks to them you can, for example, find the nearest coffee shop, pick a spot to jump out for a ride or even explore the real world through Augmented Reality. As for the new Client Libraries, they are now featured with support for Swift and Go

— — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Well, If you haven’t used Foursquare’s API yet, feel free to study their getting started guide. You will be able to create an account and have your first API call in 5 easy steps.

Based on: A New Experience for Developer Documentation & Resources by Arin Ray.

Original post.