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.
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.
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.
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.
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).
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.
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.
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.
The following structure is required for every Icecat API manual guideline:
If you have any questions or need any help, please contact us directly
Read further: Manuals
Your email address will not be published. Required fields are marked *
Comment *
Name *
Email *
Website
Δ
