In software development it is very necessary to do detailed documentation of every stage,which should be clearly understood by anybody else later either for continuing the work or maintenance, notes Dr R Srinivasan

"Good software engineers spend more time in design and development and take an easy attitude to document their design ideas and procedures undertaken "

In any product development, it is absolutely essential to have clear documentation of the projects and it is all the more important in the development of software products. Following the basic principle of life cycle in software development, an organisation must train the team on documentation and should insist that it is done at each stage of the life cycle. The contents of the documents should not only be specific to that portion of the development but also be very clear to be understood by anybody else at a later stage, either for continuing the work on that particular portion or as part of maintenance support.

A good document also helps the quality department at the time of peer review at each stage. It is always understood and expected that the vision and insight of the author is an essential part of understanding the documentation. However, in practice, good software engineers spend more time in design and development and take an easy attitude to document their design ideas and procedures undertaken, and it may lead to a situation that does not have clear documentation. They may feel satisfied that the code is finished but they don't realise that if it is not documented clearly with explanations, nobody will make any sense out of it. On the other hand, effort may be wasted on documentation of analyses, which may not be understood by anybody in the development team. Under the extreme case, the documents are prepared casually just for the sake of satisfying the expectations of the management. The antipattern that arises due to this is termed as, "throw it over the wall".

The refactored solution is to train everybody in the organisation, including the management, on how to write a technical document relevant to software development. Once it is done, the next step is for the project manager and project leader to inculcate the habit of writing the document, in the members of the team at each stage of planning, development and testing. Periodical reviews of documents must be done and the review reports also must be documented for taking the necessary and corrective actions, if any. The slogan is that the practice of good documentation will speak for the quality of work done by the team and hence about the organisation's strength.

The next antipattern that we discuss will be the one which may happen when the project team lands up in an inordinate delay in executing projects, because, at the initial stages, they might have been concentrating on something that is not connected with the project in any way. On the other hand, it may also happen that the management asks the team to wait or gives uncertain and conflicting directions.

Ultimately the team may be spending more time in the initial phases of the life cycle development, like requirement analysis and planning, and then steps into design and development. The management at this juncture will realise the slippage that has happened in the schedule and so will direct the team that the development must progress immediately. Imagine, what will happen at this stage? Urgent and unscheduled meetings for the development staff will be called for at the time of which ambitious and unrealistic demand for software delivery will be demanded. Such meeting and the associated antipattern is called the 'Fire Drill'. Due to the pressure mounting from the management as well as the customer, the team will tend to compromise in software quality and testing.

An effective refactored solution for this is through the process called 'sheltering', under which two alternative project environments, viz internal and external, are created. According to Dr Thomas Mowbray, majority of the development staff operate in the internal environment with the focus being on the long-term and continual progress towards software delivery. He further says that the internal project environment can proceed to construct the internal model, independent of changes in external techno-political issues. It is also found to be most effective in software developments associated with long duration projects developed in stages through iteration. On the other hand the external environment part is just to take care of the relationship and correspondence with entities external to the project.

( To be continued)

(The author is Chief Technology Officer, Internet Component Management Group, Bangalore and can be contacted at: r.srinivasan@iCMGworld.com)