Documentation. Supposedly the bane of every programmer, system administrator, or techie person who'd rather be Doing It than Writing About It. Those same people are also the first to complain about any lack lustre documentation of technology they're trying to use, once again proving that irony is not dead. Therefore, I'm going to complain some more, because it might make me feel better, and because I think I've got something else to say along the way.
The short version of my argument is this: if it's not documented, it may as well not exist.
Obviously I need to expand on that a bit. What do I mean by documented? At a minimum, that means that how to use it needs to be explained. Sometimes the user interface is extremely clear and obvious to almost everyone, so the level of explanation is going to be minimal, e.g. "Fill in the form with the requested information. Fields marked in red are mandatory; the others are optional. When you have finished filling it in, click on the big green button marked GO". Other times, for more complex tools and applications that have more flexibility and more options, you're going to have to go into much more detail. In describing "how" to use it, you will need to detail the interactions between the choices the user has to make. More importantly, you *must* explain the implications and limitations of the choices made. I have lost count of the number of times I've read documentation that says something like: "In the field marked 'foo', enter a value for 'foo'". And that's it. Microsoft, I'm looking at you right now, but you're probably not the only culprit. Usually 'foo' is not something obvious like 'address', or 'name', but something that I can guess is going to be important later, but I don't know in what fashion. But let's take the example of "Name"; even for something that simple, I need to know what the implications are. Is this a one-time choice? Is it just a name for me to reference the thing being manipulated? Is this going to show up in the final result, product, printout, or something else that a customer might see? All of these will factor into my choice of what to enter into that field.
A couple of things to note here:
In simple cases, "documentation" may just be text on the screen that's part of the User Interface (UI), although it should be available elsewhere as well.
A simple UI, which either leads the user through the process, or draws on reasonable levels of cultural pre-knowledge, counts as self-documentation.
A poor UI design will require *more* documentation. You can do yourself a lot of favours in the documentation stakes by making the UI simple and obvious.
The more complicated the technology, the more documentation is required on how to use it. Complication is related to the number of choices the user has to make, and it's probably a square law relationship or similar i.e. complication = <number of choices>^2, in that the more choices there are, the more interactions there may be between them.
But "How" is not enough; it's only part of the problem. The other questions that may need to be answered are the journalistic staples: Who, What, When, Where, and Why.
What does it do, and Who should be using it? Let people self-select when at the early stage of deciding if this is the right tool to use.
When should you use it? Are there circumstances when it's inappropriate, or not going to do what people want.
Where do you use it? In technology, this is as much about what data to use it on. Where is it appropriate, where is it going to do the right thing.
Why use it? This is almost marketing, as it amounts to promotion, but it's important. It helps to understand why it was created, what problem it's trying to solve.
Those 'W' questions actually cover a lot of common ground, so answering all of them for any given feature, in separate fashion, is unlikely to be necessary often, but the documentation needs to cover the whole area.
And the important thing is: this is required for each and every feature. For minor features, the 5 'W' questions will often be summed up fairly quickly in a single sentence or short phrase, but they need to be considered. For major features, there could be quite a bit to bring up, particularly if the feature is an optional part of a larger product. When would you consider using this optional feature? What are the implications for performance? Disk space? Other optional features? If you have this turned on, what else might need to be turned on, off, or be considered. All of these are important, and if they're missing, you're asking your users to figure it out by blind luck.
Now I glossed over "minor features" above, but do not forget them. If you have an obscure option, document it. If it's not exposed via a GUI dialog somewhere, and the user has to type the name of it into a text file, or a set of preferences somewhere, then it is absolutely useless unless it's clearly documented. Preferably with keywords that will allow it to be found by normal searching. If it isn't, you wasted your time implementing it for anyone but yourself. No Twinky. Bad Developer. It may as well not exist, because no-one is going to find it without delving into the code. Some of us like doing that. Most don't.