Image for post
Image for post

A New Experience for Developer Documentation & Resources

Arin Ray
Arin Ray
Nov 20, 2017 · 3 min read

Documentation is one of the most important aspects in building a strong developer community. Earlier this year we launched an entirely new version of, packed with features to help developers get started and explore our location intelligence tools.

In addition to updating the site’s branding, our team overhauled the existing documentation. A month since launch, we’re excited to talk about how we built it, and share some of our learnings in this post. We’ll first discuss infrastructure changes and then delve into some features.


Here is a breakdown of our developer documentation infrastructure.

Content Management

Upon approaching a redesign, we explored a number of technologies before settling on the Jekyll framework. This helps us transform markdown documents into a reusable documentation platform. Additionally, we added some custom plugins to make it easier and faster for us to update our documentation.


We run a simple script to build an image from our Dockerfile and expose our pages via a Nginx web server. Ngnix also handles the redirects from our old documentation URLs to the new ones.


Builds are automatically picked up on-commit from master via Travis-Ci and trigger the deployment process. This decouples our docs from everything else, and allows for us to push live updates in a matter of minutes.


Here are some of the major feature improvements:

  • Search


We built a search engine using ElasticSearch so developers can find keywords, specific endpoints, error responses, etc. It’s also reindexed every time we push an update to our docs site. We added this functionality with the future in mind, creating an API that will allow us to integrate into 3rd parties seamlessly. This makes integrating directly into IDEs like Xcode and Android Studio simple.

Image for post
Image for post

Endpoint Pages

Endpoint pages now have API responses! This makes it simple and easy for developers to see the expected output from our endpoints. These are programmatically generated to make sure we always display the right response.

Image for post
Image for post

Sample Apps & Libraries

We added several Sample Apps to showcase the power of our API such as picking a spot to hail a ride, finding the closest coffee shop, and even exploring the real world through Augmented Reality. There are also a couple new Client Libraries we added featuring support for newer languages like Swift and Go.

We’re looking to continually improve and expand these pages. In case you have a library or app you would like featured, feel free to drop us a note!

Image for post
Image for post
Image for post
Image for post

Looking Forward

Haven’t used our API before? No problem! We have a new getting started guide that’ll help you create an account and make your first API call in 5 easy steps.

We also plan on continuously improving our developer experience! Stay tuned for updated visuals to our API explorer and app signup pages.

Have feedback for us? We’d love to hear from you! Feel free to reach out to us @FoursquareAPI.


News and stories from the team at Foursquare

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store