Now I See These Everywhere
2016 Jaguar F-Type interior
So, I’m a car guy. While I’m not one of those car nuts who have a constant need to horse-trade vehicles, every few years I start thinking about the next ride. The funny thing about that is once I focus my search on one or two contenders, I start to see those cars everywhere – even though I had previously never noticed them. I’m guessing that you’ve had a similar experience with cars or some other infatuation.
It’s occurred to me recently that this ‘suddenly visible’ phenomenon also applies to emerging technology trends. Stick with me here and I’ll connect the dots.
API Doc Spotting
At xMatters, we’ve been working hard on developing a powerful new xMatters REST API. Obviously that’s a great thing, and I’d like our documentation for it to be just as impressive, but I felt that we weren’t quite delivering the information in a truly developer-friendly way. For me the goal is to publish documentation that gets people excited about creating integrations with our product. Having a great-looking and easily-consumable API doc is a cornerstone of that goal.
As with so many things in technology, I felt that I couldn’t be alone in thinking that there must be a better way. So I did a research spike and – with the help of one of our UX gurus – was able to figure out that a lot of folks had based their API documentation on an open-source framework called Slate.
…And Now I See It Everywhere
Perhaps the best canonical of the Slate approach is represented by Stripe’s API reference – it has a persistent menu on the left, reference documentation in the middle, and code examples in a variety of delicious flavors on the right.
That layout is great for moving your eyes back and forth between, say, a list of parameters and code samples that include those parameters. And, I can scroll through the document and never ‘lose’ the main menu – and that menu also indicates my menu location in the docs so that I don’t get lost. These relatively simple design changes result in faster comprehension and a more immersive experience. That’s fancy talk for “This is cool.”
Once my eyes had been opened to Slate, I saw it everywhere, which strongly suggested to me that it was time to see if we should be getting on board as well. On the theory that “if I could do it, anyone could,” I recently did a Slate proof of concept using some of our REST API documentation as sample content.
The result is that I’m now collaborating on the API docs with the xPert who is principally responsible for defining the new API specification. We quickly realized that there are some technical hurdles that we’ll need to address to get us where we need to be – but in any case I’ll update you on our progress in a future post.
In the meantime, perhaps you’ll also be seeing Slate all over the place like or here. If you need me, I’ll be car spotting.
Read the complementary research report.
Complementary Research Report
Monitoring and alerting can deliver important benefits when used together.
Please read the new independent Gartner research paper, Complement IT Infrastructure Monitoring With IT Service Alerting, for a report on how monitoring and IT alerting can help your business.