Avalara Developer Network Developer blog

Open Source Documentation

slate screenshot

Since launching this developer site three years ago, we’ve made continued improvements to both the content and the site itself. One of the areas that has seen the most change is the API reference - it’s a tricky thing to present that much information in a way that is easily traversed, navigated, and searched, while still intentionally guiding the reader. There is still room for improvement, but we’ve had success with an open-source tool called Slate.

Slate allows us to manage the API documentation in markdown and preview real-time changes with a local middleman server, making it easy to work on documentation offline (great for airplanes!). Changes are tracked through git, and we check in changes on GitHub.

Eventually, I’d like to be able to maintain documentation in way that is a little more DRY (the documentation of the same property (say, DocCode) in multiple places for multiple methods introduces more opportunities for inconsistency), but that’s a long term goal. Until then, changes are easy to make and the documentation source is easy to read.

Subscribe via RSS!

Back to posts