DerekTP’s blog

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.

1and1, and their associated company FastHosts, don’t have a great reputation for customer service.  I’ve been using 1and1’s Sharepoint hosting service for a couple of years, and don’t have any real gripes with them for the service. But now I no longer need that service, and so want to cancel it.

1and1 have a comprehensive account system, and although a little complex, it does most of what you need to do. Except cancel a contract, of course. You can add to, transfer in, modify, upgrade, extend etc… but cancel? Oh no. Eventually, if you do a SEARCH on the FAQs (it’s not available in the contents list) you can find a document on cancellation. Seems you have to log in at an entirely different site (and know your 7-digit account number - the other logins are happy to accept any domain name you have registered under your account). The online part of cancellation is fairly straightforward; but then, just when you think you’ve done it, you’re at a page with a couple of links. Click one to send an email confirmation to yourself which contains a link that you follow to confirm. Fair enough, but why can’t that email be sent automatically? 1and1 obviously hope customers overlook that step and they can charge for another year.  To cancel any domains associated with the contract, you click ANOTHER link to open a PDF form which you must sign and FAX back to them.

Now, the page says that the fax number is on the form. It’s not. In fact, it’s not anywhere on the site. I did, after quite a bit more searching, find a fax number for 1and1’s contract department, and have sent my fax to that number. But of course they may complain that it’s the “wrong” fax number. So I hand-wrote a comment pointing out the omission of the fax number, and stating “Unless I hear from you, I will assume this instruction has been accepted by 1and1, and I will not be liable for any further costs as a result of 1and1’s failure to comply with this instruction“.  I was thinking, on past experience with 1and1, that they are likely to take ANY route to try and bill me again despite my best efforts to cancel. After sending the fax, though, I spotted a disclaimer on the form “Hand-written or electronic amendments to and comments on this form will not be taken into account and will be considered non-existent“. 

This is the electronic equivalent of sticking your fingers in your ears and singing “nah nah, I can’t hear you”.  I doubt very much it would stand up in court, but it underlines 1and1’s attitude towards customer service. You may draw your own conclusions.

OK, so this is my first blog post here. Just intalled Wordpress, and getting to know it.

Wordpress, eh? Yes, it’s free, it’s supported by my hosting provider (Fast2Host, bless ‘em) and everyone knows how to navigate a Wordpress blog. After all, it’s used by millions of bloggers the world over, right?  So it must be pretty bug-free and easy to use, right?And so it is, basically. Five minutes after clicking “install”, here I am, blogging away.

But you see that apostrophe up there in the blog title (and also in this posting title?).  Funny thing, apostrophes (and double-quotes too, for that matter). You see, because they’re almost universally used by database systems to mark a piece of literal text (and distinguish it from a database command) , apostrophes themselves can be tricky to get into databases. They’re used in HTML, too, and various other places. And so to enter an apostrophe into a database, or show it in HTML, there are various work-arounds; special character sequences that tell the software “what comes next is an apostrophe, but don’t treat it like that, just handle it as plain text”.  And most of the time, that works. Except that when setting up the blog, I entered a quote, and it came back displayed as \’. I edited it, thinking I’d mis-typed it. Still showing as \’  - and a second instance, I’d not seen first time around, was now \\’.  Each time I edited, it added a backslash.  As a developer, I quickly twigged that I needed to enter the “encoded” version, ' - now it displayed fine. I went back to admin to make one more little tweak, hit save, and voila! I was back to \’ again.  When Wordpress displays ‘ on the public pages, it correctly displays it as a quote, or apostrophe. But it does the same thing when you edit, so that when you save, and then display again, the quote is “corrupted”.

Now this isn’t such a big deal. No planes have crashed, no power stations exploded, no pacemakers failed.But it’s an indication of just how fickle software can be. Sometimes my clients alert me to “issues” in software that, on the surface, appear really trivial, but also really obvious - how on earth could I have delivered software with such an obvious problem?  But software testing is not a “do it once and forget” process; no doubt the developers of Wordpress tested that admin screen many many times, and never spotted what, to me, was a glaringly obvious issue.  So this is no way a gripe with Wordpress. But it does make you wonder, if a piece of software as much used as Wordpress has glitches and gotchas of this type, is it any wonder that so many computer systems sometimes behave oddly, or that, now and again, even the most accomplished software developer slaps his forehead in a “doh!” moment when a client points out an “obvious” mistake?