Acuracy is improtant
And not just in general text (as in this article’s title).
I’m currently in the middle of enhancing a website for a client of mine. We’re building in some server-side processing that communicates with a webservice, by POSTing some XML. The complication (not that it should be) is that the owners of the webservice are in Australia.
They provided what seemed to be a comprehensive set of instructions on using the service, but on following them to the letter, hey-ho - it didn’t work.
First up, they’d added username/password authentication to their site, without mentioning this in the documentation. Very easy to resolve, but it took 24 hours to get the email to Australia and a return response.
Great, so now we can hit their webserver. Except that now, when authenticated, we get a 404 “not found” response. Another 24-hour round trip query later, and yes, they’d mistyped the URL in the documentation - wrong case. (In fact it turns out it WAS correct in one place in the documentation, but wrong in the place I’d taken it from).
OK, now we can POST the data, and get a response; this time it’s complaining about “missing field XmlData”. Now, this isn’t a proper SOAP service, they just accept XML data within a standard POST field named “xmlData”. Note the difference in case there? The error message states “missing field XmlData”; their documentation calls it “xmlData”. So I spent a while with various combinations of upper, lower and camelcase trying to get their service to recognise my input. Eventually I realised it was a bug in my code anyway, but it was something I’d have spotted a lot sooner if the error message had matched the fieldname ACTUALLY needed (which was xmlData, as per the documentation, not XmlData, per the error message).
So now we’re really getting places, right? Actually, no. Although we’ve resolved the server authentication issue, the data also contains an affiliate ID and password field. Despite copy/pasting from their “welcome” email, it’s not being recognised. I’ve a feeling (though it’s just that at present) that the ID is valid only on the “live” server, not the “development” server I’m currently pointing at. The documentation pack ONLY gives the development URL, however, and asks developers to test their code (and have the service confirm that all is well) against the development server before going live. So, there’s going to be another 24-hour delay (at least) whilst we sort out IDs and passwords again.
In short: typos, missed information and the right hand not knowing what the left is doing has turned this very straightforward task into a marathon. When I, as a freelancer, price up a job like this I make assumptions about how long certain tasks will take; and I also make the assumption that, given an apparently “definitive” document, I have the necessary information. Each time I spend 10 minutes testing and then have to put everything down for a day whilst waiting an email response (not to mention writing the email itself as well) costs me nearer 40 minutes, as I have to load/unload projects, remind myself of the next task, collate and file documentation etc.. etc.. and on a small job like this, what was supposed to be a nice productive task quickly becomes a wound haemorraging profits away. Multiply this wastage by a few dozen times as other would-be users of this webservice around the world suffer the same problems, and quickly hundreds of pounds are being wasted for the sake of a 15-minute proof-read and a little care.
It doesn’t matter how much you’ve tested your software product, if the instructions on how to use it don’t work, your efforts are in vain. I’ve long held the belief, and this example vividly illustrates, that documentation (in terms of user manuals and guides) is an integral part of software development and that it, too, demands rigorous, controlled, planned testing every bit as much as every line of code that your developer writes.