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… |
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)