Email: Password: Remember Me | Create Account (Free)

Back to Subject List

Old thread has been locked -- no new posts accepted in this thread
Jan Waclawek
03/12/06 13:09
  03/12/06 13:23

Read: 495 times

#112023 - viewpoint
Responding to: Ian Bell's previous message
There are different veiwpoints to the topic as there are big differences in the circumstances of each project of each of us.

My task is usually more complicated than what Ian described, the clients are far less knowledgeable and far more demanding then usually. The v0.1 cannot be a mockup but it has to be the full application; however, there are substantial changes down to the skeleton even in v3.2, as the client finds out what he wants finally. And, it has to fulfill various contradictory requirements of several involved parties...

So there is no universal approach to documentation as there is no universal approach to electronic design either. This is not to say both of them are necessarily ad-hoc. I believe there are typical tasks which are best solved using standard methods, but if all problems would have predetermined solution, the programming would be no more fun and I would be looking for some other job - nuclear physics, molecular biology, neural surgery, anything else similarly trivial :-)))

But there might be some cues or general guidelines of course. A very good approach is what Erik mentions: document the internals of the program in the comments, document the interfaces in a strictly technical manner, do the user manual as a skeleton and leave it to anybody to blow it up - if the user wants a 300-pages manual with infinitezimally small informational density as the common software manuals today are, let him have it; the smart user could have the skeleton document.

The best documentation is written in such way, that you ask yourself all the time, whether you would understand it if you would be the user - but this is as hard to achieve as hard is it is to teach well (in fact, both are essentially the same proces).

Jan Waclawek

List of 24 messages in thread
How do you manage Documentation?      Vignesh Prasad      03/10/06 06:04      
   As soon as you finish??      Andy Neil      03/10/06 07:13      
      User Manual      Vignesh Prasad      03/10/06 10:48      
         it all is very simple      Erik Malund      03/10/06 10:56      
   too late and totally wrong      Erik Malund      03/10/06 07:36      
      you have an easy life won't you      Jan Waclawek      03/10/06 08:40      
         Of course, you only have enough informat      Erik Malund      03/10/06 09:12      
            more on the above, the beauty of the hoo      Erik Malund      03/13/06 06:51      
               in C?      Jan Waclawek      03/13/06 07:51      
                  please do not accuse me of unnatural act      Erik Malund      03/13/06 08:02      
         Design Info      Ian Bell      03/11/06 07:13      
            viewpoint      Jan Waclawek      03/12/06 13:09      
               General Principles      Ian Bell      03/12/06 13:38      
                  the clients...      Jan Waclawek      03/12/06 14:00      
                     Client Variety      Ian Bell      03/14/06 05:26      
                     It's like I said last month ...      Richard Erlacher      04/02/06 18:25      
                  Great      Vignesh Prasad      04/01/06 00:31      
                     I, J OK      Ian Bell      04/02/06 15:10      
                        Repetition      Vignesh Prasad      04/03/06 10:40      
                           My old DOS based suite...      David Smith      04/03/06 11:17      
               Two categories      Oliver Sedlacek      04/03/06 02:34      
                  MIL498      Mahmood Elnasser      04/03/06 13:35      
   write the documentation first      Richard Erlacher      03/11/06 11:50      
      Good points..      Vignesh Prasad      03/12/06 10:05      

Back to Subject List