The following article will touch upon the issues of sense and form of the process of documenting, in conjunction with different methodologies of software development. In order to avoid excessive amounts of text, common-use terms and names will not be explained. An inset at the end of the article contains references and useful links.

The following article will touch upon the issues of sense and form of the process of documenting, in conjunction with different methodologies of software development. In order to avoid excessive amounts of text, common-use terms and names will not be explained. An inset at the end of the article contains references and useful links.

The source materials have been supplemented with comments and information obtained from members of teams working on projects of varying sizes, related to the companies: Adapt, AtosOrigin, Kruk Systemy-Inkasso, Lucent Technologies, XPBrains (Ukraine) and Rodan Systems, as well as from staff members of Wroc³aw University of Technology; to all of these people I would like to extend my warmest thanks.

Necessary evil, The foundation of a good project, Unjustified expense, Vital tool - sense and form of the documenting process in software development project is a controversial topic and opinions about it are greatly varied. The most extreme opinions, characteristic for the so-called eXtreme Programming radicals, state that the best (implying: the only needed) documentation is the source code of the program. Here it is worth emphasising that Kent Beck - creator of the eXtreme Programming methodology - doesn't postulate complete elimination of documentation, merely its reduction. This group promotes the thesis that documenting results in losses of concentration on the most important element of the project, that is - on deployment of a product (in this sense the product is software; as we will show later, documentation can be a product as well). The expense of time spent on documenting can cause an increase of the project's expenses and, in consequence, can threaten to collapse or at least delay it. On the opposite end of the spectrum one can find supporters of formal methodologies, for whom all phases of implementation are charted with documentation. Such people represent the approach based on models like CMMI (Capability Maturity Model Integration); this model, created by Software Engineering Institute, defines processes taking place in course of software development. Within these processes it has been defined what kind of documentation should be produced (granting freedom with respect to the form of these documents, though). Management of documentation is distinguished as a standalone process.

Documentation

Every member of a project team, as well as the customer, is either a creator or an user of documentation. Extending the understanding of an IT project beyond its lifetime cycle, as defined by Software Engineering, we can construct a general picture of the project documentation world. Such a world is shown in Figure 1. (which should be treated as a mere draft overview - only select documents have been shown, furthermore it is possible that, depending on the course of the project, times of creation of particular documents can be enmeshed in a different way). Management of documentation is does not involve only projects, test plans and code, but also correspondence with customers, the contract (above all), schedules, cost estimates, task lists et cetera. The shape and form of technical documentation pertaining with the software being developed itself, is usually influenced by the applied project-leading methodology. Organisational and enterprise documentation is similar in form - however, in projects based on formal methodologies, organisational documents will likely be in much greater abundance. Appearance of certain documents is implied by adherence to quality standards; this is very well defined by the standard ISO/IEC 12207, pertaining with documents in the lifetime cycle of software (see: Figure 2.).

Figure 1. Documentation created and applied in a software development project

Figure 2. Example: document groups defined by the ISO/IEC 12207 standard (based on „IT Project Management Handbook” by J. Sodhi and P. Sodhi)

The Roles of Documentation

The most important role of documentation in software development processes is believed to be communication. This involves communication both within the team and with the customer or with the organisation the team comes from (a simple diagram illustrating can be seen in Figure 3.). Analysing this role of documentation it is easy to understand why teams employing the eXtreme Programming methodology do not require much documentation on paper. Working in pairs or small teams, often in the same room, results in emergence of something referred to as oral documentation (a good approach to documenting in a small team - but bad for documenting customer requirements). The role of communication is served by each kind of documentation mentioned in Figure 1. On the other hand, more care in developing documentation is required by projects carried out by distributed teams; there it is one of the most important communication channels.

The second important role played by documentation is control over and quality assurance for the project and the product. Software development in accordance with ISO9000-4 standards is often referred to as document-driven development; under such circumstances, documents mark every element of the project. Should one consider this approach too fossilised, it is possible to employ the ISO/IEC 12207 standard mentioned earlier on. ISO/IEC 12207 postulates partial inclusion of documentation into the products as its integral component (which can be understood as a postulate of referring to documentation in contracts).

Treating documentation as a product does not serve only to live up to quality standards. In certain products, (technical) documentation is a good and is therefore subject to the same sales processes as the software itself. This is particularly striking in case of cryptographic solutions (where the documentation is more expensive than the product itself) and other innovative solutions.

In large projects, consecutively-appearing documents can be used as indicators of progress of a project, the so-called milestones. Furthermore, the lack of complete documentation (technical in this case) hinders further development of a product beyond its initial version. A small product can easily be created without documentation; however, its further development may turn out to be very expensive. In case of a large product the lack of documentation would greatly complicate even its creation.

A d v e r t i s e m e n t

sum:

0 €

» Library of the Month
» Workshop
» Software Engineering
» Programming Tools
» Interview
» High quality and
secure programming
» Reverse Engineering
» Portable GUI
» Artificial intelligence