Designing tutorials – some insights for API documentation
I’ve just published a blog post on the Google Geo Developers Blog, about a new design for the Google Maps API tutorials. I’d love some feedback from technical writers. If you have a few minutes, would you head on over there and let us know what you think?
Advertisements
Posted on 21 February 2017, in APIs, Google Maps and tagged API documentation, Google Maps APIs, technical communication, technical documentation, technical writing. Bookmark the permalink. 2 Comments.
Sarah, this is really good. 🙂
I have just had quick peruse of the content and it looks great (will return for a deeper look soon).
It is focused, to the point, clearly sets expectations and outcomes and is easy to follow.
Maybe at – Try it yourself “code above are three buttons.” an image of the buttons will make it quicker to find, otherwise full marks!
I have been planning on a similar activity, when time permits, to change focus of some of our help from feature focus to more of a use case approach.
From a development and developer’s perspective, it’s all about features in a release, as devs work hard to create or improve new functionality and are very proud to announce new features (and rightly so).
Users however, which includes developers in this instance, are motivated by reasons to use a ‘feature’. It’s great to have Swiss Army knife product, however what are all these widgets and ’things’ for???
Thanks for the opportunity to review.
David
Hallo David
Thanks for a great comment. “From a development and developer’s perspective, it’s all about features in a release” – so true! Also, it’s easier to document things feature by feature. Sometimes, it’s good to take that step back and look at the whole use case.
I like your idea of adding a screenshot of those 3 buttons. Their look and position has changed a few times over the past few months, as the doc site’s UX team experimented with ways of making the buttons findable. We’ve needed to be a little vague in our description of the UI (sound familiar? 😉 ) but I think the UI has settled down now.
Cheers
Sarah