Making the manual the requirement of the program

[waldemar.hersacher]

I know most manuals will be written after the programmers have done most of their work.

Most programs arise from an idea and will be specified in a more or less detailed requirement document(s). Next programmers start their work building user interfaces and writing the code. At last someone is starting to write a manual to explain what the program does and what steps are to do to get a specific result. If you have a detailed requirement you can derive the manual from it otherwise you must use the program and talk to the programers and/or designers to know what the program will do.

Since the user interface and the functions you can do with it are part of the requirement I think that writing the manual must be completed before the program will be filled with code. The programmers must provide all the windows as graphics which can be done with the user interface editors of their development environment. Most of them must be in various versions depending of the states the program can have. And they must think a lot about the data because it must be consitent in these windows.

With the graphics and the requirements from the meetings with the program designers you can start writing the manual. You can get a sort of interactivity using hotspots with all the menu entries, buttons and all the other interactive controls. You can also do partly a useabilitiy test because you can count the number of mouse clicks you need to do a certain task. And you will find out which state of the user interface and program have been forgotten.

At the time the management says that is the manual and program we will, the programmers can start building all the code (if they do not start complaining about: that is technical impossible or that is to expensive). Now its time to advertise the product and put the manual in the internet. And someone will look at it and say couldn't you change this or that. Use thisone as your beta tester. He have already read you manual and knows what the program should do which allows him to make qualified tests.
And in the end you do a testing using the manual as the reference and when there is a difference the programmers have to change their work.

What do you think? Isn't it better to do first the manual and than the program?
I'm talking about a program because I'm a programmer but I think this could be also true with any sort of technical product.

[Tim Green]

Waldemar,

What do you think? Isn't it better to do first the manual and than the program?

Interesting discussion! In the best of all possible worlds probably yes, but I don't think it's going to happen in reality, particularly with shareware products.

However, I do think that the both the help authors and the beta testers should get involved in the development process much earlier than they normally do, because that can help to make both the program and the documentation more usable.

What generally happens is that both the testers and the documentation people get called in much too late to fix major errors in program usability and structure, which occur because programmers have a different perspective to normal users.

I've often thought there would be a market for a kind of "simulation tool" to test the usability of program concepts without actually doing any major coding. Maybe based on Flash or something like that with graphical building block tools, so that you could roughly emulate the behavior of a program and test it out on users before you've committed to major programming overheads.