Wunderlist API documentation on GitHub

When we published our Wunderlist API documentation earlier this year, we wanted a simple and easy solution for letting developers ask questions or report problems. Our first thought was Stack Overflow. It’s an amazing resource for developers and they encourage companies to participate in answering questions. However—totally understandably, by the way—they don’t want to be the primary support channel for companies.

We briefly considered building our own solution. The effort of doing so, however, wasn’t in our time budget. So, we punted and added Disqus comments to every page of documentation.

Over the next few months, we found that while Disqus works well on blog posts and other web pages, it wasn’t really an effective tool for us to keep track of user requests and questions on our API docs. Where things really broke down for us is when we tried to keep track of who internally was keeping track of questions and which issues were still open and needed an answer. Of course, this wasn’t due to any real shortcoming on the part of the tools that Disqus provides. Instead, it was how we were trying to use it. It wasn’t the appropriate tool for the job.

Earlier this month, Medium shipped their API and provided documentation in the form of a simple markdown file in a GitHub repository. My first thought was to wonder how Marcin Wichary felt about the presentation and layout of the documentation. After all, the folks at Medium care a lot about the way they present text around here.

My second thought, however, was admiration for the absolute simplicity and practicality of the solution. A solution that comes with built issue tracking and even the ability for outsiders to submit pull requests with suggested changes. My third thought was:

“Duh! Why didn’t we think of that?”

I quickly proposed to our team the idea of following Medium’s lead and moving our docs from our developer site to GitHub as well. Our engineers loved the idea. After all, we spend all day interacting with GitHub. On the other hand, our designers weren’t so sure we should give up the look and feel of the docs on our website. We found a nice compromise with a two part solution:

  1. We externalized our API docs to github.com/wunderlist/api
  2. We pull from that repo to build the documentation section on our developer website. The content is in Markdown format after all.

While I’m sure we could have built an amazing in-house solution given enough time, we have a lot of other priorities right now. Actually, as Chad Fowler says, we have one priority and a lot of other things which also feel like priorities. Leveraging great tools which already exist is a much more pragmatic solution and in the end, it will serve developers—both inside and outside of Wunderlist—better than our previous solution.

Thanks Medium for the idea! ❤

A single golf clap? Or a long standing ovation?

By clapping more or less, you can signal to us which stories really stand out.