How Foursquare Succeeded In Managing Developers’ Documentation

New York

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, 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.


Content managementJekyll 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


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.

Follow me on Twitter @JavaShopPoland or visit website


Best Polish Java Engineers in 14 Days

Rob Renner

Written by

Tech Entrepreneur | Engineer from background | #FinTech #Startupper #Java @JavaShopPoland |



Best Polish Java Engineers in 14 Days

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade