One of our key goals is to ensure that developers and technologists can rapidly evaluate and use our Identity & Access Management API. We recently analysed how well our technical manual supports that goal by looking at the learning styles it supports.
There are many models of learning styles, but a simple one to understand is Neil Fleming’s VARK model which classifies four styles:

Visual a preference for depiction of information in graphs, charts and diagrams we’ve included many diagrams in our overview material, particularly to illustrate the different access control flows that our API supports
Auditory a preference for hearing information or engaging in conversation while we’re always available for conversations with teams evaluating or deploying our API, we’re going to add some screencasts to the manual to further support this learning style.
Read/Write a preference for the written word, and also learning through writing we’ve aimed to cater for a variety of users, from CTOs needing high level
overviews, through to reference material for developers.
Kinesthetic a preference for doing – learning through experience and practice the manual features a ‘try it’ tool which provides a playground for testing API calls, but we felt we could provide a better learning tool…

tutorial We felt the ‘Kinesthetic’ learning style – learning by doing – was something we could really improve upon, and set ourselves the challenge of making an interactive walkthrough of the key elements of API. We had the following goals:

  • takes less than five minutes
  • guides the reader through IP and WAYF-based authentication and authorization
  • uses the live API, and not a simulation
  • allows the reader to make changes to see what happens
  • provides illustrative curl command lines to make further self-paced exploration easy

We’d like to invite you to try our new 5 minute tutorial and let us know what you think.
Because the manual includes various live links with our API, it’s password protected. If you’d like to take a look, just get in touch.

Credits

Image adapted from Parchment by Nacnud (used and adapted under cc-by-2.0 licence) and A book of Old English Ballads (public domain)