A New Experience for Developer Documentation & Resources
Documentation is one of the most important aspects in building a strong developer community. Earlier this year we launched an entirely new version of developer.foursquare.com, 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.
Infrastructure
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.
Deployment
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.
Automation
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.
Features
Here are some of the major feature improvements:
- Search
- Endpoint Pages
- Sample Apps & Libraries
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.
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.
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!
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.
