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

Back to Subject List

Old thread has been locked -- no new posts accepted in this thread
Ian Bell
03/12/06 13:38
Read: 475 times
United Kingdom

#112024 - General Principles
Responding to: Jan Waclawek's previous message
Jan Waclawek said:
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.

Whilst every project and every client is different, I am convinced there are general principles for both design and documentation that can be applied to any project. The only differences will be the emphasis each receives as dictated by the project specifics.

1. Start with a Product Specification. You need to write down right from the start the product functional and performance requirements. If nothing else, in Jan's case that defines what version 0.1 is supposed to be. This document can be subject to changes reflected in its issues number and the changes can be clearly defined in the document itself.

2. Divide the project into stages. Each stage must have defined goals. Each stage should have a project plan which defines what needs to be done to achieve the stated goals, how long it will take to achieve, the resources needed and any inputs needed from the client. Give the client a copy so he knows what to expect and when and also what his responsibilities are.

3. Use a Day Book for each project. Write down all your technical thoughts, calculations, circuit diagrams, code fragments, test results etc in it. Never hand it to the client. The day book is a Design Document.

4. Write a Design Specification. This is the design response to the Product Specification. It says how the design will achieve the functional and performance requirements.

5. Write a Test Specification. This says how you are going to verify that the design meets the requirements.

6. Document the details of the design as they occur. Much of this will already exist in the Day Book but with software this means, as Erik says, in the code itself.

I have never met a client that did not appreciate a professional approach as outlined above.

I still use a Day Book even though I am now retired.


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