Documentation failure

DerekT P

An app I support interfaces to a large number of 3rd party webservices. Often the documentation is poor or incomplete. Last week I integrated to one that seemed pretty well documented. At one point it says

xxxxxx can be called in one of four modes:
● Redirect (default)
● XML
● JSON
● iFrame
The mode can be specified by setting the 'mode' query string parameter

and subsequently refers to "XML mode" several times. I coded up the interface, ran some tests; and got non-specific errors every time. Eventually the 3rd party company got back to me with the following explanation:

mode=XML should be mode=xml i.e. the "xml" is case sensitive.

:wtf: :omg: :mad: :doh: :sigh: :( :| It works now but it's wasted two hours of my time and delayed the integration by the best part of a week. TEST THE DOCUMENTATION TOO, YOU WALLYS!

GibbleCH

Agreed...but how does 2 wasted hours delay integration nearly a week?

DerekT P

If does when they don't reply to your query for 5 days!

Nagy Vilmos

As is our wont to point out, the API is wrong. :-D It should be an enumeration and then case doesn't come into it OR it should be throwing a fracked exception saying "Unknown mode, must be 'redirect', 'xml', 'json' or 'iframe'."

Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett

BobJanova

Yeah, the documentation is wrong too but the API should be giving you a clear exception if you give it invalid input.

Nagy Vilmos

Open API's should always work via 'design by contract'. As long as the pre-conditions are met, a valid post-condition will be reached, otherwise an exception is raised and the state is unchanged.

Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett

DerekT P

Absolutely agree with you. However, regardless of the API itself, the documentation was remiss in not specifying what the actual parameters required are. "Test-driven development" does not mean sending data to the API to "see what happens"! Documentation is PART of the deliverables for virtually any project. Whilst we may not like it, documenting our stuff is vital and not only that, but the documentation needs testing too. By that I mean if you follow the documentation, without any pre-existing knowledge, is the outcome correct? Whether the API returns just "Invalid" or "Invalid; should be one of 'xml','redirect' ..." etc doesn't change the fact the documentation is just plain wrong, by omission in this case. The depressing thing is this isn't new or unusual; I blogged about this over 2 years ago http://www.smallofficesolutions.co.uk/wordpress/index.php/2009/05/11/acuracy-is-improtant/[^] and in that case the API itself was returning a message referring to "missing field XmlData" whereas the documentation referred to "xmlData" (and the documentation was right in that instance, the API was wrong!)

Sander Rossel

From another perspective: we got some requirements from a customer on what we should build for them. They want a Form with lots of information on many tabs. The documented description of a tab, for example the 'customer' tab: "Shows info on the customer"... Really? I'm glad we got requirements for that! This was written by people who specialize in writing those documents. I guess writing good documents just isn't easy.

It's an OO world.

public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
}

BillW33

Over the years I have seen lots of bad documentation; from missing specs to APIs that are just plain wrong. I am no longer surprised when the docs do not match what the app actually does. Apparently documentation is an afterthought at many companies. :sigh:

Just because the code works, it doesn't mean that it is good code.