Project notebook
Remember that the program code is a necessary but not a sufficient deliverable if there is a need to understand decisions taken. Documentation adds to your explanation. However the main purpose of software development is to produce quality software and documentation should serve that purpose. The approach taken to software development, the problem being addressed, contractual obligations and other factors will determine how much to document and what to document.
Keeping a project notebook is a disciplined approach to organising your thoughts and actions as a software developer. Your project notebook is a record of notes, thoughts, drawings, ideas and decisions (and the reasons for taking those decisions) as you work on a project. In its simplest form a project notebook will be paper based, but it could be recorded in files on a personal computer.
For it to be effective, you should keep your project notebook with you at all times, so that you can use it, save it and review it. There is no limit to what you can record in the notebook. For example, you can note down what your users say about their needs, make some preliminary sketches of models or even record telephone numbers and URIs that may be useful while at work.
Whatever you record, you should date-stamp your notes, and review them on a regular basis to ensure that your questions have been addressed and that you have extracted the information that is useful on a given project. You must keep accurate dates and times for the information recorded in your notebook for the following three reasons (all of which relate to traceability):
- your project notebook may be required as evidence in some enquiry or even in a court of law
- it helps you to review what you have done and how long you took to do some task
- it facilitates learning.
Activity 11 Traceability
Part A
- a.Why is traceability important to the development of software?
- b.How does documentation contribute to traceability within a development project?
- c.Which activity or activities in the development process (shown in Figure 5) are most affected by poor documentation?
- d.For what kind of software system might you minimise or even avoid any documentation?
- e.How would you characterise agile documentation?
- f.Why is it important to review the contents of your project notebook?
Answer
- a.Traceability is important for the reconstruction of significant events. In software development it should be possible to follow all the activities undertaken in response to a proposed change. In particular, you should be able to trace backwards from an implemented component or components, through their design, to a given requirement.
- b.Within a development project, documentation records the progress from requirements to implementation (and beyond). It is possible to identify each requirement and follow the actions taken to implement a solution to that requirement. You might, quite simply, be required to show that you have implemented each requirement correctly.
- c.All seven activities will be affected by poor documentation. The maintenance and quality management activities will be most affected because they rely on the existence of traceability within the outputs of a development activity. (You saw this problem earlier when we looked at legacy systems.)
- d.If a proposed software system is likely to have a short lifetime and will be discarded after use, it may be acceptable to minimise or avoid the task of documentation.
- e.Agile documentation should be gathered with a purpose, should be easy to use and above all should justify the effort put into gathering it. There is no reason why this shouldn’t apply to any kind of documentation but often software development produces heavy documentation that is rarely used.
- f.The act of reviewing your notes helps you to identify what worked and what did not, as long as the notebook records accurately what you did and when. A review helps you to trace the events that led to the decisions you made since your previous review. Regularly reviewing your notes also enables you to check that you have followed up on all the decisions that you made.
Part B
What are the main problems associated with the development of software? You should be able to identify at least six.
Answer
Here is our list of problems that affect software development (you may have identified others):
- difficulty in capturing all the user requirements
- difficulties in managing and developing large and complex systems
- not meeting users’ requirements and avoiding dissatisfaction with the completed software
- continual changes in user requirements (often referred to as requirements creep)
- maintaining poorly documented software
- the presence of errors introduced unknowingly during development
- a changing world leading to changes in the needs of the users and decreasing the usefulness of the software
- low productivity of those developing software, and difficulties in measuring that productivity
- ensuring the quality of a software system.
Part C
- a.How do you think a large-scale project differs from a small-scale project in terms of the management of the development team?
- b.What management steps might be taken to tackle the problems that arise in a large-scale project?
Answer
- a.As the size of a project increases, so does the number of people involved, and consequently the complexity of the interactions involved, and the difficulty of managing the team. As with programs, the greater the complexity of interaction, the greater the chance of errors occurring due to poor communication.
- b.One of the functions of software project management is to manage project complexity. One way to achieve this aim is to modularise project teams by splitting them up into a number of groups. Each group performs a specific task and communicates with the other groups through one person (for example, the head of the group). Another way, encouraged by an agile approach to development, is to encourage practices of communication and cooperation in development, such as working in pairs and having daily short meetings.
Part D
Process models sometimes show only the software-creation activities and exclude software maintenance. What problems are associated with the use of such models?
Answer
If maintenance is not mentioned, it is likely that it will not be considered to be an integral part of the overall software process model. This may result in a design that does not take the needs of maintenance into account, and hence a product that is difficult and expensive to change. This is especially likely if time and/or budget are already tight.
Part E
What kinds of software system would be best suited to an iterative and incremental development process?
Answer
Software systems where the problem can grow incrementally or where it falls naturally into partitions, each of which represents a fairly self-contained unit that could be developed and delivered on its own to provide the users with a useful chunk of functionality, would be well suited to this model. An iterative and incremental approach allows several design issues to be tackled simultaneously and enables the system to be implemented in relatively small steps in order to contain the complexity. Of course, this assumes that the design can be partitioned.
Part F
Figure 8 shows a spiral process for software development. Into which quadrant of that figure does each of the seven technical activities of Figure 5 fit? Notice that there is not a one-to-one match.
Answer
The analysis, design, implementation and testing activities all fit into the ‘develop and verify a (partial) solution or product’ segment. The analysis activity also overlaps the evaluation quadrant where objectives and risks are analysed. The testing activity overlaps the ‘review and plan’ quadrant. The maintenance, project management and quality management activities (including configuration management) operate in all four quadrants.
Part G
It has been said that ‘the maintenance activity begins with the first deliverable of a development project’. What does this imply about the maintenance activity?
Answer
This refers to the fact that there could be deliverables, such as requirements documents, that exist prior to any software being built, and these also require maintenance. For example, you might detect errors or inconsistencies in a document that lists the important terms in your users’ domain, or you might have to respond to changes in the environment, which may be due to new regulations or market forces.