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?

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 21 February 2017, in APIs, Google Maps and tagged , , , , . Bookmark the permalink. 2 Comments.

  1. 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.


    • 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.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: