Have you felt frustrated when you hit F1 and the help didn’t show up? Would it have helped you and saved you a bunch of head bangs? One of the important things I have learnt in my experience of developing and using software is that the said benefit is derived only if it is used; and derived to the fullest only if it is used right. Translated for a business, the expected ROI can be achieved only if it knows how to use the software. This can make or break a project, or sometimes the business itself.
There are multiple ways in which a software developer can ensure this, in addition to providing intuitive GUI - by training, help, support, or innovative self-healing software. The common element in all these is documentation. The documentation can be provided in the form of online/offline help, manuals, courseware of training sessions and also forums sometimes. All these things now take part in ensuring that certain business tasks happen, and become part of the business documents.
Basic purpose of the documentation is to impart knowledge to the user, so that he can focus on the business task and use documentation to deal with the software.
The documentation has to be done carefully, because one who is reading it might not know much about the software technology. An assessment of the user’s skill is important. It is quite possible that this software can be his/her introduction in the world of computers! One can also use different forms of documentation - text, audio and video, recordings, demonstrations; I am sure many more innovative techniques will keep emerging.
If your user is another developer, there are different ways of creating documentation from the software code itself, like doxygen, Javadoc, PHPDoc, and many more. They can extract not only comments but also design from the code.
Not only the developers, but the businesses should also realise that documentation will enable them to reap benefits of their software investment. They should make sure that they don’t just buy the software, but learn how to use it.
Technorati tags: documentation, help, f1, training, support, gui, learn
Copyright Abhijit Nadgouda
March 6th, 2006 at 9:35 am
[...] Documentation Is Not Optional [...]
April 14th, 2006 at 9:30 am
[...] In my opinion, documentation should also be more easily available so that users can find guides to usage. The irony with documentation is that, it should not be necessary for usage, but should be available whenever required. Too much documentation and effort for must-read documentation can discourage a user. Currently open source community help is available through forums and is distributed. This documentation should be converged at a single location and made easily available. [...]
July 14th, 2006 at 10:59 am
[...] I think this is the biggest effort cost of providing flexibility. Without supporting documentation it is just another bundle of controls and dialogs for the user. Usable and extensive help can provide the necessary education to the user about the application. [...]
November 1st, 2006 at 8:23 pm
[...] Help has been one of my favourite topics. Roger Johansson talks about Don’t Provide an Accessibility Statement by Peter Krantz. Overlooking the exaggeration, the article stresses on providing help to the user instead of a technical accessibility statement. Accessibility is for the user. It can get across quicker if it is explained as help instead of a standard. Accessibility is still technical jargon! I had to create a help page for this blog because one of my readers was not versed with weblogs and feeds. However it is just the start, not complete yet. [...]
November 19th, 2006 at 10:46 pm
[...] Documentation is probably one of the most hated subjects for most of the developers. The biggest reason is it is often difficult and tedious to be articulate in specifying what to do or what has been done. I have mentioned earlier why documentation is necessary for the user, in one form or another. A lot of professional argue against this by saying that the software should be intuitive and easy for the user to not require documentation. However, it is also true that the ROI from software is out of using it the right way. This might involve not only the software operations but using software to be part of certain business process(es). And the documentation should talk about this. [...]
October 23rd, 2007 at 9:33 pm
[...] my opinion, documentation should also be more easily available so that users can find guides to usage. The irony with [...]
October 23rd, 2007 at 9:50 pm
[...] think this is the biggest effort cost of providing flexibility. Without supporting documentation it is just another bundle of controls and dialogs for the user. Usable and extensive help can [...]
November 1st, 2007 at 10:12 am
[...] should usable and intuitive enough to guide the user by itself, without user documentation, which I do not fully agree with. I acknowledge that the RTFM attitude is bad, but help should be handy as well, especially if your [...]