DerekTP’s blog

Not so very long I blogged here about the need for accuracy in documentation. Well, here I am again, trying desperately not to whinge but to instead underline the need for doing documentation well.

Once again I’m trying to implement a 3rd party web service for a client, and the documentation is again just plain wrong. Apart from being so sparse as to be positively cryptic in meaning, there’s a column specifying the maximum size of fields; but the example XML they give blows those field lengths away. Either the example data was never tested, OR the spec is wrong. Of course, I shouldn’t really need the example anyway; but since the spec fails to specify things like date formats, case sensitivity and so on I’m forced to examine the example for clues as to what’s needed.In many cases, of course, documentation isn’t needed. If you’re designing a website, the interface should be intuitive, and have enough helpers and pointers to allow the user to work with it without resort to a manual. There are all sorts of things that can help here, from adopting well-accepted standard layouts and conventions to using tooltips and pop-ups appropriately.

Years ago, in the dim-distant past when Windows 3.11 ruled supreme, Microsoft published a “style guide” that laid down the actual menu names application developers should use, where those menus should go, the size of buttons etc, right down to detailing in pixel-specific detail the colours and layouts for the corner of a button. Now in those days it was hard to make your application distinctive or different, user interfaces were pretty boring rather than pretty, but at least once you knew how to work one Windows application you could learn others very easily. The web has blown that model out of the water, and there are some pretty amazing visual metaphors that pass for buttons these days.But then there’s a whole raft of software that most certainly DOES require accurate, detailed documentation, and that includes web services. The documentation effectively IS the user interface for these types of application, and they’re certainly the first point of contact for a new user. First impressions count, so for goodness’ sake not only get the documentation factually correct, but make it easy - a pleasure if possible - to use.  Otherwise your (potential) users will get frustrated and fail in their implementations.

It’s not difficult - the simplest approach (once you’ve been through the planning, design, drafting, writing, proof-reading stages, of course) is to give your documentation to someone who does NOT know the product, and ask them to install / use / whatever, using just your documentation. They should not only be able to follow the instructions, but be able to do so easily, confidently, and know why they’ve done what you’ve instructed them to do. They should be able to access ALL aspects of your software.On this last point, I’ve long maintained that software features should not be discoverable only by accident - the user should be directed to the full feature set (at their own pace, of course) without needing to stumble across features.

To my mind, the rot in this area set in with Windows 95. Before then, Windows users accessed their file system primarily via the built-in “File Manager”; in other words, the USER managed the FILES. In Windows 95, Microsoft decided that the user wasn’t responsible enough to manage their system, and replaced File Manager with “Windows Explorer”. At one stroke, the file system became an “unknown” quantity, and the user had to “explore” - navigate through the unknown, never being sure of what they might find. It might seem a small point, but I strongly believe it marked a turning point in software - no longer were users in charge, but the software was and, if the user was lucky, they might work out how to use it.

(BTW, at Small Office Solutions we don’t work that way - if we write a service or a tool that doesn’t have a “traditional” user interface, we write documentation for it, we proof-read it, and we get someone to “test” it. We believe that’s the way it should be done.)

So, as you may have seen on my website’s homepage, I’ve been shortlisted for the Remote Employment Awards in the Freelance Contractor category.

Apart from surprise and delight, my overall feeling about this is that it’s both a huge honour and a responsibility. It’s something like 1 in 7 people in the UK are now “self employed” (in the broadest sense) and whilst not all of these could be described as “freelance consultants”, freelancers make up a significant proportion of the country’s workforce. However, judging by press coverage, and more importantly political decision making, you could be forgiven for thinking that there’s only a handful of us. Whilst there have been some concessions to “small business” over the past few years (reduced Corporation Tax rates, no necessity for audited accounts, simplified company structures etc) few address the “micro-business” explicitly. Conversely, this Government seems to view anyone with the nous, determination and vision to be working for themselves as to be doing so primarily to avoid paying “fair” taxes.

Firstly, it’s apparent that there will never be any agreement on the meaning of “fair”, and to use it in political terminology at all will only ever inflame things, and can never succeed in reaching agreement with all parties. That aside, it must be equally apparent to anyone with any common sense that choosing to “go it alone” is far too big a step for anyone to take for the dubious “benefit” of paying slightly less tax. As a freelancer, working through my own limited company, I qualify for protection under the Working Time Directive (except that as a Director, I can exclude myself and, if I’m to make a decent living, have to work far more than 48 hours per week). Similarly, I qualify for sickness benefit and paternity leave. But should I be in a position where I might choose to take those benefits, I will be losing far more in lost earnings than I could stand to take in benefits, so of course I just soldier on. (As it happens I feel like death as I write this, but am here at my desk working anyway). I pay not only employees’ NI contributions, but employers’ as well (or my company does). But since these payments directly reduce my company’s profits, this is a direct cost to me personally - unlike employees of a larger company. When you try and balance all the pluses and minuses of freelancing, it quickly becomes clear that this way of working is not supported by our Government, and it’s a hugely risky step to take (if leaving paid employment to start up, anyway).

So what does this have to do with the Awards? Well, I see them as a news “hook” on which to promote not only my own business, but the situation that freelancers in general find themselves in. Coincidentally, the awards come at a fortuitous time, just a few weeks before National Freelancers’ Day which is a great opportunity to fly the flag for freelancers everywhere.

When I heard I was shortlisted, one of the first things I did was conduct a poll amongst my clients, to gather their views on both Remote Working and Freelance Consulting. Around 40% of the respondents enjoy Remote Working for at least part of the time; 100% felt that freelancers offered a more flexible, better value service than the “big name” consultancies. That perhaps was inevitable, since my sample is of people who have already chosen to work with freelancers.  But all were able to give specific advantages to their own businesses of working with independent freelancers, and that alone gave me reassurance that, whether with the Government’s support or despite the lack of it, demand for freelancers will continue.