Icecat API Manual Guideline

This Icecat API Manual Guideline is written to help to increase the usability and consistency of the manuals. But also the specification of APIs that Icecat is providing to its users. A good specification reads like a manual, and writing the final manual is the final check on the specifications of an API from a usability point of view.

Take care to first read the Iceclog Editor Guidelines, as they are an integral part of these more specific guidelines.

Use English “for Dummies”

API manuals should be in English. Further, an API Manual is not only read by developers, but also by all kind of other staff. So, take care that your manual is written in clear and understandable English “for Dummies”. Make complex stuff simple, so that even non-techy outsiders can understand what it is all about, if they would skip the code sections.

Like any text, have it been checked by a native-English speaker, before publishing it.

Coding by Example

Make it as easy as possible for a user, new to the field, to make use of the API that you describe. Therefore, start with a code example that does the job for one Open Icecat data-sheet. And, expand from there towards the general structure of API calls.

Take care that every attribute is explained. In case that attributes need to be explained, like language codes with extensive tables, take care that these are included by reference and are maintained on a central location.

Self-explaining Code

Developers have the tendency to produce code that is not readable for outsiders, not using complete English words but (weird) abbreviations. Code elements that are not self-explainable, need to be made self-explainable, which makes an API manual more readable as a consequence.

So, don’t say “Lang” for a language code, but say “Language”. Don’t say “No” for an sorting or ordering number, but say “OrderNo”.

Also the terms of the domain should be used consistently, and the semantically most correct terms should be used. Use “BrandName” in stead of the more generic term “Supplier” in case that only the names of product brands are used.

Sometimes values like “200” are dropped in an API call. The reader has to guess that it is for a time-out in seconds, and the techwriter of the manual also doesn’t explain this as he or she didn’t understand it either and forgot to ask.
Better require here “TimeOut=’200′” as a self-explaining attribute.

If you don’t know what something is, ask! Explain every detail.

Use CamelCase

When writing a manual, you will discover that developers have been inconsistent. They might use “Brand_name” in one place, and “BrandName” in another. We want you to make sure during the specification phase already, that the developer has to use CamelCase (so “BrandName” is correct).

Separate Advanced Options from the Quick Guide

Don’t complicate your manual by immediately introducing advanced options. Better hide advanced options and include them in a separate post. Link to them from the introductory (quick guide) manual.

So, leave out options, functionalities, and attributes that you not need for the most common implementations of the API that you describe. Move these to advanced user sections.

Tips should stand-out

The common mistakes that users of the API and readers of the manual make, should be covered through tips that are not to be missed by the reader. And they should be unambiguous!

Don’t hide your tips.

Visualize!

Show visuals for explaining how the results will look for an end-user of the app. And, visualize the data flow, data model, and other key technical elements. Start with end-user visuals. And put technical visuals in appendices. As they are there for reference and for a smaller audience.

Structure clearly

The following structure is required for every Icecat API manual guideline:

1. An introduction clearly stating the purpose of the manual
2. A reference to an explanation of Icecat and its services
3. The key terms used in the manual
4. The API service explained
5. API calls explained by example (and references to external examples)
6. The general structure of API calls
7. Tips that cover all the typical user mistakes
8. References to all other relevant manuals and materials including these guidelines
9. How to get support from Icecat

If you have any questions or need any help, please contact us directly