One of the current developments in technical communication is the development of a common way to present API documentation. At present, there are a number of different design patterns that organisations are using, but, as with many things, there seems to be a desire to establish a de facto standard.
One part of this has been to establish the topics that should be covered in an API guide. Typically, this includes a conceptual overview, how to obtain authorisation keys, getting started and the important reference information of the endpoints, parameters code samples and error codes. The reference information includes having code samples that developers can copy and paste (and tweak to their situation). This often means different samples for each development environment.
The second part has been the the information design aspects of how the content should be presented. The Stripe API is one that probably has been copied the most. This organises the content into columns, with the code samples on the right side of the screen.
Last week, Tom Johnson tweeted about a new design pattern used by Lucybot:
RT: “A New Open Source Interactive API Documentation From Folks Over At Lucybot” https://t.co/8mSkjKLVKg#api#techcomm@apiwareio
— Tom Johnson (@tomjohnson) February 17, 2016
This offers a console, accessible as a tab.
This is quite an appealing approach because it could be replicated across a number of authoring tools.
The UK’s Government Digital Service is looking to establish a common standard for API documentation on the Gov.uk website, and this could have quite an influence on other sites looking for best practice to copy.
Which design patterns have you seen and liked? Share your thoughts using the comment box below.
Leave a Reply