Testing, Testing, 1 2 3…
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.)