Offices: HQ in Chicago, IL
Industry: Multi-channel marketing services
Tools used: Confluence, JIRA
I had the pleasure of speaking with Brendan Flynn, Senior Director of Product Development, at ShopLocal, a couple of weeks ago about how they have standardized on Confluence for developing and publishing their API documentation.
ShopLocal, a leader in multi-channel marketing services, offers a complete suite of innovative digital solutions that connect advertisers and consumers – online and in-store. ShopLocal’s industry-leading SmartProduct business solutions (SmartCircular, SmartCatalog and SmartDelivery) enable more than 100 of the nation’s top retailers, including Target, Best Buy, Home Depot, CVS, Albertsons and Sears, to deliver highly interactive, targeted and localized promotions to shoppers through online circulars, display advertising, search, social media, digital out of home and mobile. ShopLocal is the retail division of PointRoll, a wholly owned subsidiary of Gannett Co., Inc.
How did you hear about Confluence?
I had used Confluence at a previous company. I started using Confluence when it was version 1.10, pretty early on. Confluence fit the bill best. Very quickly we were able to convert all of our existing content and really change how as an organization we collaborate. The wiki is the lifeblood of the organization and we use it for everything from our API documentation to a lot of the internal initiatives such as policies and processes. It’s the knowledge base of our organization. When ShopLocal was acquired by PointRoll, we were able to easily migrate their SocialText wiki to Confluence using the Universal Wiki Converter. Our wiki as of September 2010 has over 12,000 pages and 58,000 page versions.
With regards to the API documentation, who writes the docs and who consumes it?
Writing is a collaboration between product management and the developers. Technically, anyone in the organization can edit or create new documentation, but we found that it’s only the core developers that edit it. We’ve locked down the permissions so our customers cannot edit the pages, but they can leave comments.
We’re an agile dev shop so it’s pretty seamless to take our user stories and convert them to high-level release notes. We wanted to maintain consistency across the application. Every API call includes a brief description, required, optional and conditional parameters, URL examples in addition to the expected output in XML and JSON format. A wide variety of companies are consuming our API to distribute local deals in a variety of mediums, including the retailers (the Targets, the Best Buys, Staples and Home Depots of the world) and their development agencies, to independent application developers. We work with a wide variety of developers, agencies and retailers. Our main objective with the documentation is to make it simple for people to adopt our API and start building applications immediately.
What were you using for your documentation prior to the wiki?
Prior to using Confluence, we were using a 100-page Microsoft Word to distribute our API documentation. Using Word for our documentation caused a lot of unintentional issues. For example, we version our API, we come out with a new release about every quarter. So you can imagine, with Word docs getting passed back and forth, developers didn’t always have the latest information, and we were often developing with older releases and using the wrong nomenclature.
It was also very difficult for us to communicate changes. We relied on email communication to distribute updates. In some cases, it may have been a year since the last time a developer had requested the documentation. The best thing with a wiki, versus multiple versions of Word documents flying around, is that there is a single source of truth.
Tell me about migrating content to Confluence.
Do you use any plugins to help with documentation?
No, not really. Confluence ships with free, out-of-the-box plugins and macros that work for us and we’re using Documentation theme. We use Confluence’s page templates for consistency. Each API call has a consistent look and the kind of information is consistent from page to page. We use the content by label macro quite a bit, for example we use this with our FAQs. We’ll tag it with API FAQ and then we have the page dynamically built using the macro.
And we use the code macro quite a bit. Probably one of the things I like using the most is inclusion libraries. I’m a really big fan of using inclusion libraries. We can put information into the root level and use page inclusions to insert content on different pages. One example is how we manage versions. Because we have multiple versions of the API, we’ll have an include that says, “this refers to an older version” with a link to the latest version. Inclusion libraries save a tremendous amount of time for we make the change in one place and it updates all the pages that have the included page.
What are the benefits of using a wiki for your documentation?
Some of the additional benefits that we’ve seen include providing documentation consistency. Developers now always have the latest version of the documentation, they know where to get the latest version. They watch the pages so they can get an alert when a change has been made. We use the comments so they can ask questions and provide feedback on the docs, which as a product manager is useful to get that feedback because it helps validate what we’re building.
The best API documents you’ve seen make it easy for people to build applications. That was our objective. We’ve come a long way from where we were. Certainly, Confluence made that so much easier for us.
One of the unintended benefits is that we spend less time talking through the documentation with customers. Now instead of having to explain the documentation, we spend time talking about the applications they want to build.