Which documentation for software maintenance?

Abstract

Software engineering has been striving for years to improve the practice of software development and maintenance. Documentation has long been prominent on the list of recommended practices to improve development and help maintenance. Recently however, agile methods started to shake this view, arguing that the goal of the game is to produce software and that documentation is only useful as long as it helps to reach this goal.On the other hand, in the re-engineering field, people wish they could re-document useful legacy software so that they may continue maintain them or migrate them to new platform.In these two case, a crucial question arises: "How much documentation is enough?" In this article, we present the results of a survey of software maintainers to try to establish what documentation artifacts are the most important to them.

Optimising agile development practices for the maintenance operation: nine heuristics

“…& in relation to the agile characteristic of iterative development: maintenance work can be organised into sprints (iterations), but the task synergy and common goal assumed in development work are usually missing in maintenance & in relation to focused work objective: maintenance sprints are subject to interruption by urgent customer demands and there are few common delivery points or integrated releases (Bennett and Rajlich 2000) & in relation to teams working closely together: maintainers predominantly work on individual tasks on many different systems and system variants (Bennett and Rajlich 2000) & in relation to close customer involvement: maintenance engineers typically work with many customers with many small change requests, they are seldom on-site, and there is often little close interaction (Bennett and Rajlich 2000) & in relation to face-to-face communication: this is not always necessary or productive in maintenance, due to the diverse nature of the tasks undertaken (Kitchenham et al 1999) & in relation to light documentation: maintainers consider documentation necessary to maintain the integrity of the evolving system, and to help with program comprehension in future maintenance work (de Souza et al 2006;Prochazka 2011) & in relation to frequent testing: comprehensive system testing is usually impractical, testing limited to immediate impacts of current fix (Junio et al 2011) & in relation to motivation through collective ownership: collective ownership may be irrelevant where maintainers are working on independent tasks in multiple codebases, motivation is difficult without common tasks and delivery points (Kitchenham et al 1999;Singer 1998) & in relation to knowledge transfer through openness: openness and information sharing may be of little value if tasks are un-related, and there is no coherent release or natural deadline (Bennett and Rajlich 2000) Table 2 summarizes the results of the literature investigation.…”

“…Maintenance, though under-researched, is by far the predominant activity in software engineering. The majority of commercial projects are built over a previously developed codebase (Svensson and Host 2005), and maintenance represents typically 90 % of the total cost of a typical software product (de Souza et al 2006). Cockburn (2006) argues that agile methods represent an evolutionary kind of development in which maintenance activities are subsumed in an iterative sequence of software deliveries, but there is no evidence that this has become common practice.…”

“…Aveva adopted the principle that every customer should experience some progress in a sprint; after that the relative urgency of the request as expressed by the individual product owner should determine priority. Heuristic 5 (derived from Tables 2 and 4, issue 5) Balance documentation and face-to-face communication appropriately Traditional software development methods (Paetsch et al 2003) and traditional maintenance approaches (de Souza et al 2006;Prochazka 2011) are more dependent on documentation than agile methods, which to a larger degree depend on face-to-face communication (Nerur et al 2005). Maintainers constantly work with changing systems and program comprehension, so they understand the need for good documentation.…”

“…Heuristic 6 (derived from Tables 2 and 4, issue 6) Write (minimally) structured use cases for communication Task specification was a case in point where Aveva needed good documentation; the minimal user stories of agile practice tuned out to be inadequate for their needs. Use case diagrams and specifications are regarded important in maintenance (de Souza et al 2005(de Souza et al , 2006, for representing requirements and developing tests (Choudhari and Suman 2014;Kajko-Mattsson and Nyfjord 2009). At Aveva the writer of the use case was (in many cases) no longer the engineer undertaking the task.…”

Annotation Mechanisms to Manage Design Knowledge in Complex Parametric Models and Their Effects on Alteration and Reusability

“…These annotations can communicate a programmer's intent, or it can be used with other specific software engineering tools [Kellens et al, 2010]. Previous research reveals that source code comments are the primary resource used by developers to understand code [Souza et al, 2006]. In fact, many program failures and "bugs" are caused by miscommunication among developers or misinterpretations of code, often triggered by improper or lack of source code documentation [Tan et al, 2007].…”