Introduction

We recently shipped an updated documentation site in the quiet of night. This week, we want to break the silence and let you know the essentials: What we did (lots), and why we did it (to make it better). Here’s our changelog of new things to look out for in the docs.

Adding versions

We kicked off our updates by deciding to remodel our client SDKs. This requires supporting docs for both the current versions of the SDKs as well as the remodeled versions which were in the works: iOS v4 and Android v2 client SDKs, currently in beta. We realized that the new version system would give us the opportunity to rethink the architecture of our documentation.

SDK drop-down UX

In our usability studies we found that users went straight into the content and often missed our global SDK picker.

Considering the docs now need to support multiple SDK versions, it made sense to relocate this essential piece of UI from the global header to something more local. The SDK selectors and the options are now contextual and related to the way the content in each page is scoped: client, server-side, or agnostic.

Improved reading experience

In addition to the larger layout changes affected by the SDK drop down, we took steps to improve the overall reading experience of the docs. The sidebar navigation has been moved off fully to the left so that the docs are much easier to read, and parse at-a-glance. We’ve made typographic changes to make headings and section dividers clearer, and we’ve switched up our code snippet theme so the reading experience is more seamless.

Better URLs

Improving readability doesn’t stop at the content. Considering the addition of versioned docs and more contextual SDK presentation, it made sense to re-think our URL structure. Since our approach to documentation is feature-first -- meaning we filter our content by feature > SDK > version -- we could easily port that structure over. A URL like /guides/apple-pay/client-side/ios/v4 lets you know precisely where you are in the guides and the content you should expect; overall, the URLs are much more readable and shareable.

Technical stuff

To implement many of these changes, we needed to lift the hood of our docs application and take a look inside. This was an opportunity to isolate good, re-usable code; remove irrelevant code; take care of any tech debt we have acquired; and implement a new, efficient request pipeline. For the request pipeline, we stuck with express.js because it’s quick and we like it. We added Front-matter blocks to the content markdown files to separate our content for the contextual SDK selection, and help extend the metadata available for any page.

---
platform: client  
title: Client-Side Implementation  
---

Things we’re still working on

Our documentation site is cleaner inside and out, but we’re not done improving it, by far. Watch this space for updates that include language support for Swift, more UI enhancements, and clearer content structures.