ITEA-AGILE-D2 10 - v1 0

Agile Software Development of Embedded Systems Version : Date : Pages : 1.0 2006.03.
09 39
Agile Deliverable D.2.10
Agile Documentation in Mobile-D Projects
Authors
Tanja Kynknniemi Kaisa Komulainen
Abstract
The focus of this document is on agile documentation. The research concentrates on gathering information from current agile documentation literature, and documenting in agile projects which use the Mobile-D framework. The document is divided into a theoretical part and an empirical part.
Status
Fin al
Confidentiality
Public
Page
: 2 of 39
Version: 1.0 Date : 09.03.06 Status : Final Confid : Public
CHANGE LOG
Vers. 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0 Date 24.10.05 Author Kynknniemi, Komulainen 9.11.2005 Kynknniemi, Komulainen 14.11.2005 Kynknniemi, Komulainen 28.11.2005 Komulainen, Kynknniemi 30.11.2005 Kynknniemi 12.12.2005 Kynknniemi 14.12.2005 Kynknniemi 20.12.2005 Komulainen 21.12.2005 Komulainen, Kynknniemi 9.3.2006 Komulainen, Kynknniemi Description First version of the deliverable. Writing background theory. Finishing background theory. Changes according to suggestions. Writing case descriptions. Changes according to suggestions from Pekka Abrahamsson. Agile documentation in Mobile-D context and projects Updating Research design Finalizing the document To be reviewed -version.
Copyright AGILE Consortium
Page
: 3 of 39
TABLE OF CONTENTS
1. 2. INTRODUCTION.......................................................................................................................................4 SOFTWARE DOCUMENTATION IN AGILE DEVELOPMENT.......................................................6 2.1 CHALLENGES IN SOFTWARE DOCUMENTATION .....................................................................................6 2.2 AGILE DOCUMENTATION .......................................................................................................................7 2.2.1 Documentation in Agile Software Development Methods.............................................................9
2.2.1.1 2.2.1.2 2.2.1.3 Scrum ..................................................................................................................................................... 10 Extreme Programming............................................................................................................................ 11 Crystal .................................................................................................................................................... 12
2.2.2
2.2.2.1 2.2.2.2 2.2.2.3
Methods for Agile Documentation ..............................................................................................12

Joint Application Development .............................................................................................................. 13 Agile Modeling....................................................................................................................................... 14 Rapid Production of Documentation, 7 steps.......................................................................................... 16
2.2.3 3.
Model for Agile Documentation ..................................................................................................17
RESEARCH DESIGN ..............................................................................................................................20 3.1 RESEARCH METHODS...........................................................................................................................20 3.2 AGILE RESEARCH SETTING IN MOBILE-D ............................................................................................21 3.3 CASE DESCRIPTION ..............................................................................................................................23 3.3.1 uniCorn .......................................................................................................................................23 3.3.2 Roger...........................................................................................................................................23 3.3.3 Avalanche....................................................................................................................................24
4.
RESULTS ..................................................................................................................................................25 4.1 DOCUMENTATION IN CASE PROJECTS ..................................................................................................25 4.2 PROCESS OF CREATING DOCUMENTS ...................................................................................................26 4.2.1 uniCorn .......................................................................................................................................27 4.2.2 Roger...........................................................................................................................................27 4.2.3 Avalanche....................................................................................................................................28 4.3 STRUCTURE OF AGILE DOCUMENTS .....................................................................................................29 4.3.1 uniCorn .......................................................................................................................................30 4.3.2 Roger...........................................................................................................................................31 4.3.3 Avalanche....................................................................................................................................32
5.
CONCLUSIONS AND LIMITATIONS OF THE STUDY ...................................................................34
REFERENCES..................................................................................................................................................37 APPENDIX........................................................................................................................................................38
Page
: 4 of 39
1.
INTRODUCTION
Documentation has a significant role in many software projects regardless of the used software development approach. The purpose of documentation is for example to share information and to preserve knowledge. In practice, documentation is used in software projects e.g. for describing user requirements, software architectures, design decisions, source code and management issues. These documentation needs can change according to a project and its needs. Thereby one problem with documentation is in fact to decide which documents are necessary and how detailed information they should contain. Documents are also often too long and there are too many of them. It is as well costly to create and update documents. The risk is that documentation costs are greater than what the benefits are. (Rping 2003; Kylmkoski 2003)
One suggested solution to these problems is agile documentation. An agile approach to documentation aims at being both lightweight and sufficient. The purpose with lightweight and sufficient documentation is to prevent people from spending too much time and effort on documentation. Lightweight and sufficient documents are also easier to handle and use from the users point of view. Agile documentation aims also at being accurate, up-to-date, readable, concise and well-structured (Rping 2003). However there is not much knowledge yet about agile documentation. This research aims at providing more knowledge of how agile documentation has currently been approached in agile projects. The intention of the empirical research is to get background information especially on how agile documentation is created, maintained and structured in three case projects applying Mobile-D (hereafter Mobile-D) methodology. In addition this research gathers information about agile documentation from existing literature. The research is divided into a theoretical part and an empirical part. The following research questions have been set for this research:
1. How is the role of documenting presented in current agile software development methodologies Scrum, Extreme Programming and Crystal? 2. What is the documenting process in projects using Mobile-D framework? 3. What is the structure of the documents in Mobile-D projects?
This document is structured as follows: the literature review is presented in section two. This review contains an explanation of general challenges in software documentation, and also the role of documenting in three agile software development methodologies, Scrum, Extreme Programming and Crystal, is talked through. Three methodologies for agile documentation, Joint Application Development, Agile Modeling and Rapid Production of Documentation in Seven Steps, are also presented in the section two, as well as Rpings (2003) model for agile documentation. In section Copyright AGILE Consortium
Page
: 5 of 39
three the research design for the study is explained, including case descriptions and descriptions of the used research methods. The agile research setting in Mobile-D is also explained in section three. Section four contains the results of the study. This means explaining the process of creating documents in the case projects and the structure of these documents. Section five includes conclusions and limitations of the study.
Page
: 6 of 39
2.
SOFTWARE DOCUMENTATION IN AGILE DEVELOPMENT
The current agile software development methodologies do not give extensive practical advices concerning documentation, because agile software methodologies put the emphasis and value on developing software (Agile Alliance 2005). However there are some agile documentation methods which, as the name already suggests, are only for documentation. One good example is RaPiD7 (Kylmkoski 2003).
According to Rping (2003) the purpose of agile documentation is to produce better documents through various techniques. These techniques include e.g. the following: First, the documents should have useful structure that guides the reader through the material, because this way the needed information is obtained easily. Second, meaningful diagrams should be included because they can make documents a trigger for face-to-face communication. And third, the document should include a reasonable amount of meta-information that informs readers about the material; readers can then decide whether the material is for them and see how it relates to other project artefacts. (Rping 2003)
2.1
Challenges in Software Documentation
The purpose with traditional software development methodologies is to achieve predictability, stability and high assurance. This applies also to the goals of documentation. In fact traditional development methods rely on explicit documentation. (Boehm and Turner 2004) In traditional software development there is an aim for having complete and extensive documentation during the whole development process. The completeness and extensiveness of documentation can cause a risk of people focusing more on documentation instead of developing working software. (Boehm and Turner 2004) Main reasons for documenting in general are increasing understanding, sharing and storing information and keeping track of information shared. However these goals are hard to meet with traditional methods. (Kylmkoski 2003) Documents in traditional software projects often get too long. Another problem is that there are too many documents. In that situation finding the needed information and keeping the documentation up to date is difficult. (Rping 2003; Lethbridge et al. 2003) This makes sharing information and gaining understanding hard and makes the information sharing inefficient, which causes an inadequate level of understanding (Kylmkoski 2003).
Documentation can also be poorly written and finding useful content in documentation can be difficult. One major complication is that creating documentation is very time-consuming i.e. the effort
Page
: 7 of 39
and cost may outweigh the benefits. (Lethbridge et al. 2003; Kylmkoski 2003) The content of a document can present subjective opinions of the writer, and the content might not necessarily be clearly defined. Challenges can come also from the lack of proper commitment to the documentation process (Kylmkoski 2003). Thus it can be said that the traditional way of documenting software projects contains many challenges. Table 1. presents the challenges of software documentation as a summary.
Table 1. A Summary of Challenges in Documentation. Challenge Completeness of documentation Possible Consequences of the Challenge Focus is on documentation not in developing software Too long and too many documents Difficult to find needed information and to keep it up-to-date Hard to share information and to gain understanding Poorly written documentation Documentation takes too much time Document is based on the opinion of the writer, and it is not clearly defined Lack of proper commitment to the Inadequate level of understanding Costs are greater than benefits Inadequate level of understanding Inadequate level of understanding
documentation process
2.2
Agile Documentation
According to Rping (2003) there are some practical instructions for designing and making an agile document. First of all, each document must have its target readers. In agile context a document should be written to fulfil a specific purpose for the intended readers. Also background information, for understanding the document, needs to be explained. If target readers can not be identified for a document or a reason why they should read it is not clear, the document is likely to be unnecessary. (Rping 2003)
An agile document should also have a clear focus on a topic. In addition the document should offer information which is relevant to the topic, nothing more. A document is likely to have a clear focus when its abstract or summary can explain the focus of the document, its title is clear and all sections of the document consist of material which is relevant to the topic. The use of documentation portfolio is a way to achieve focused information. A document portfolio describes document types which might Copyright AGILE Consortium
Page
: 8 of 39
be needed in a project and the typical content of these documents. The documents in the portfolio vary from management, specification and design documents to documents about migration, usage, testing and operations. It is important to remember that each project should define its documentation requirements individually. (Rping 2003) The amount and variety of needed documents changes according to project circumstances (Cockburn 2005). These circumstances include many factors; needed documentation depends e.g. on the projects size, location of the team members, the projects criticality, documentation required by the stakeholders and needs of a possible follow-up project. The variety of needed documentation can also change over time. (Rping 2003)
Customer collaboration, as an agile value, is very important also when considering documentation (Agile Manifesto 2005). A close collaboration with the customer is vital for producing a good specification; to make sure that the project is going to the direction the customer wants the specifications should be a joint effort. The project team should write the specifications together with the customer. Also when making sure that foundations are laid for future design changes, design documents should focus on the rationale behind the design and explain why the particular design was chosen and why other alternatives were declined. A design document is more useful for future projects the more experience it reveals. (Rping 2003)
With agile documentation it is possible to avoid producing documents which expire too fast. This happens by addressing documentation that focuses on issues with a long-term relevance. Documents which describe the fundamentals of a project are important throughout the project. Also information and experiences gained during the project are likely to be useful for future projects. To give a good and clear general picture of the project without giving too much technical information it is possible to make an overall description of the system. This document can provide overall understanding of design principles, technology that is fundamental to the building and the architecture. This kind of general document should be short and concise. (Rping 2003)
Agile documentation does not back up heavy documentation because it does not exactly serve the readers. Even though the intention is to provide readers with comprehensive information, the heavy documentation often veils knowledge when it should instead convey it. The reason for this is that project documents are sometimes too long and poorly organised, and from these documents, it may be very difficult for readers to find what they are looking for. When the frustrated readers stop looking for the right information, the document has failed to serve its purpose. The readers can access information much faster if the document includes for example strong structural elements and diagrams for illustrations. (Rping 2003)
Page
: 9 of 39
According to Rping (2003) with agile documentation the focus should be on necessary documents, and it should be ensured that they become high-quality documents. One aspect of the quality is high legibility. Therefore the goal should be on finding a quick and easy way to produce highly legible documents. Rping gives advises for layout and typography to produce legible documents. These advises include recommendation for a document layout and typography: text on 50 % of a page, line width about two alphabets per line, 120 % line spacing, use two typefaces: sans-serif typeface for heading and serif for body, careful use of type variations, also careful ruling and shading in tables, tables and diagrams placed near the text from which they are referred, and coherent pages. Also document templates can be used to form the basis of all project documents. (Rping 2003)
2.2.1
Documentation in Agile Software Development Methods
The emphasis of agile software development methodologies is on face-to-face communication (Agile Manifesto 2005) and thereby in agile methods written documentation is often replaced with informal communication. One reason why agile methodologies do not promote documentation is that the cost of creating and keeping documentation up-to-date with constantly changing requirements and source code is high (Holz and Maurer 2003). Many agile software development methods also aim at welcoming changes and reducing comprehensive documentation (Lugi et al. 2004).
In the Agile Manifesto (2005) one basic value is appreciating working software over comprehensive documentation. This however does not mean that documentation is not valued at all or that it is not important in agile software development and agile software development methods (Agile Manifesto 2005). The lack of explicit documentation can in fact lead to problems such as people spending much time in repeatedly answering the same questions, people facing the same problems again and again without remembering the solution, not having direct knowledge exchange between people from different teams and loosing important knowledge when people leave a project or a company (Holz and Maurer 2003).
Some of the agile methodologies provide some level of guidance on agile documentation. For example Scrum (Schwaber and Beedle 2002), Extreme Programming (Lippert et al. 2002) and Crystal (Cockburn 2005) offer some guidelines about what areas of software development could be documented and for what purpose these documents are done. In all of them the characteristics vary as can be seen in Table 2: in Scrum the focus of documentation is on different backlogs, in XP not much focus is put to documentation at all, and in Crystal documentation is required yet not defined. The base for possible documents consists in Scrum of product, release and sprint backlog, in XP of story cards, task cards, release plan and iteration plan, and in Crystal of system architecture description, common domain model and screen drafts. Copyright AGILE Consortium
Page
: 10 of 39
Table 2. Agile Documentation in Scrum, XP and Crystal. Agile Methodology Scrum Characteristics in documentation documentation consists product backlog, release backlog, sprint backlog story cards, task cards, a release plan, an iteration plan Possible documents
mainly of different backlogs XP emphasis on minimal formal documentation and maximal face-to-face communication Crystal documentation required but not determined
a system architecture description, a common domain model and screen drafts
As stated in the Agile Manifesto (2005) all of these methodologies value more working software than formal documentation. However, it is not meant that documentation is un-important: there is still appreciation towards some form of documentation in Scrum, XP and Crystal. The more precise guidelines for documenting in Scrum, Extreme Programming and Crystal are introduced next.
2.2.1.1
Scrum
As an agile methodology Scrum focuses mainly on management. It introduces a new role for management; the role of Scrum Master. He is responsible for making sure that the values and practices of Scrum are being followed. Basically Scrum is a management and control process that tries to decrease complexity. (Schwaber and Beedle 2002) Scrum focuses on building software, which meets business needs, in a 30-day development period, called Sprint (Highsmith 2002). In practice Scrum enables the development team to work effectively in co-operation (Schwaber and Beedle 2002).
The documentation in Scrum consists mainly of different backlogs; Product, Release and Sprint Backlog. With Scrum management and teams can concentrate on requirements by using Product Backlog. It is a form of a requirements specification document. It is a list of all requirements including all the features and functions. It also contains technologies, enhancements, bug fixes and anything that represents work that should be done on the product. The Product Backlog is dynamic and it changes according to requirements of the product. (Schwaber and Beedle 2002) The Product Backlog acts as a base for the Release Backlog and the Sprint Backlog. The Release Backlog is a subset of the Product Backlog and it contains the features which should be in the next product release. The Sprint Backlog contains the work which should be done by the development team Copyright AGILE Consortium
Page
: 11 of 39
during a 30-day Sprint. It identifies the features to be done and also the tasks which are needed in order to implement the features. The Sprint Backlog is a subset of the Release Backlog. Progress is followed with a Sprint Backlog Graph. It plots the days and the work remaining in hours. Progress is monitored in Scrum but time reporting is not part of it. (Highsmith 2002)
2.2.1.2
Extreme Programming
Extreme Programming (XP) focuses primarily on the programming side of agile software development. XP is based on four main values which are communication, simplicity, testing and courage to make improvements to the system at any time. (Cockburn 2002) In practice XP can be seen e.g. as pair programming. In pair programming two software developers work side by side, the other does the actual programming and the other observes beside. Both developers program and observe in turns. (Agile Alliance 2005)
XPs focus is on building software through minimal formal documentation and maximal face-to-face communication. The purpose is to encourage interaction. (Highsmith 2002) Personal conversation is emphasized because information can be exchanged more effectively this way and
misunderstandings and ambiguities can be solved right away. In XP, it is assumed that if communication is intensive and it can be guaranteed, majority of the normal documentation can be left undone. (Lippert et al. 2002) The justification for not having heavy documentation comes e.g. from the facts, that XP is designed for small teams (2-10 persons), turnover of team members is supposed to be small and the customer is an integral part of the team and therefore provides constant feedback (Briand 2003). In addition, all the documents, and source code as well, created in a project belong to the whole team; anyone in the project can modify them at any time. Thus, also version control is stated to be very important in XP. Concerning the source code also coding standards are very important. These standards determine the external form of the code. Using coding standards makes the code uniform. (Lippert et al. 2002)
There are also some tools for communication in XP, which can be considered as a form of documentation. These tools are story cards, task cards, release plan and iteration plan. Story cards describe the system to be built from the customers point of view. Thus they should be written by the customer. There can also be some technical tasks which are not related to story cards. In XP task cards are used to describe these technical requirements. A typical release plan defines the deadline and functions for the next release. In long projects the release plan can be staged; it contains all releases. Each release may consist of several iterations. An iteration plan contains the plans for each iteration through the assignment and prioritisation of story and task cards. Thus, planning of a
Page
: 12 of 39
project is based on story and task cards, release plans and iteration plans. Functional requirements and a generic exemplary description of a task are also documented. (Lippert et al. 2002)
2.2.1.3
Crystal
Crystal is a family of methodologies which emphasize frequent delivery, close communication and reflective improvement. The basic issue in Crystal is that the selection of methodologies is project specific. The purpose in Crystal approach is to collect and catalogue sample methodologies from which a project can select a methodology to use. The chosen methodology can be tailored to suite specific environment and circumstances. (Cockburn 2005)
All the Crystal methodologies share the same principles. These principles include also some ideas concerning documentation. The amount of needed documents varies according to project circumstances. The amount of documentation can also be reduced by having short, rich and informal communication paths. It is also said that opposed to written documents progress is followed by milestones, which consists of software deliveries. Crystal requires documentation but it does not determine what the documents are. (Cockburn 2002)
In Crystal, the needed documentation is decided by the project team and persons who allocate the money for the project. The ideal situation is that the team produces the archival documentation late, fast and cheaply. It is of course important to decide what to document but it is just as important to discuss how to document and when; the later the documentation is left the more up-to-date it is, but on the other hand there is the risk of not documenting at all. Cockburn (2005) has recommendations for some documentation. It is suggested that teams do a system architecture description, a common domain model and screen drafts. The system architecture description shows the main components and interfaces, which are a part of the system. The common domain model is either a class diagram or a database schema, which shows the principal classes or entities of the system. Screen drafts are for showing how screens will look. They are often simply drawings on a paper, which are used to explore the way that users could interact with the system. (Cockburn 2005)
2.2.2
Methods for Agile Documentation
Methods that take agile documentation into account are introduced in this chapter. These methods include Joint Application Development (JAD) (Rottmann 2001), Agile Modeling (AM) (Ambler 2002), and Rapid Production of Documentation in 7 steps (RaPiD7) (Kylmkoski 2003). These three methods are chosen because their focus is on writing documents in an agile manner. Main goals of these agile documentation methods are described in Table 3. As it can be seen from the table, JAD
Page
: 13 of 39
and RaPiD7 are quite similar methods, because they both consider having well-structured meetings. Despite the similarity, these two methods have different goals and purposes. In contrary to JAD and RaPiD7, Agile Modeling does not make a stand on how individual documents should be written. That is because Agile Modeling is a collection of practices, principles and values. Therefore it can be considered as an ideology rather than a method.
Table 3. Main Goals of Agile Documentation Methods. Agile Documentation Method Joint Application Development Main Goals a method for running structured and facilitated meetings Agile Modeling a practice-based methodology that enables softwarebased systems to be modelled and documented Rapid Production of a method for document authoring in software
Documentation in 7 steps
development projects
Customer involvement and group dynamics play a major role in JAD meeting. The meeting has four necessary elements including facilitation, agenda setting or structured meeting, documentation, and group dynamics. Members of the meeting are assigned to strict roles, which are executive sponsor, facilitator, user, IT representative, scribe, and observer. In general JAD life cycle consists of the following phases: planning and definition, preparation, design sessions, and finalization. (Rottmann 2001; Carmel et al. 1992) Unlike the JAD method RaPiD7 defines a three-layer structure including product layer, case layer, and workshop layer. In RaPiD7 the documents are written in a team in consecutive workshops. The workshops contain seven steps, which are preparation, kick-off, gathering ideas, analysing ideas, detailed design, decisions, and closing. (Kylmkoski 2003); (Dooms and Kylmkoski 2005) Contrary to JAD and RaPiD7, AM is collection of practices, which are guided by principles and values. AM it is not a complete software process, because it focuses only on modeling and documentation. Therefore it should be used with another full-fledged process such as eXtreme Programming (XP), Dynamic System Development Method (DSDM), SCRUM, or
Unified Process (UP). (Ambler 2002)
2.2.2.1
Joint Application Development
Joint Application Development (JAD) process aims at hastening the design of information technology solutions and at the same time increasing user involvement as well as improving system quality. JAD is technique for running structured and facilitated meetings. Customer involvement and group dynamics play a major role in such meetings. First, the group builds shared goals and accurately describes the users view of the business need. Then the group gets into a problem-solving mode Copyright AGILE Consortium
Page
: 14 of 39
and jointly develops a solution. The meeting encourages to cooperation and bonding between the information system staff and the users. There are four necessary elements to a JAD meeting: facilitation, agenda setting or structured meeting, documentation, and group dynamics. According to Rottmann members of a JAD session are assigned to strict roles, which are executive sponsor, facilitator, user, IT representative, scribe, and observer. (Rottmann 2001; Carmel et al. 1992)
In general a JAD life cycle has the following phases: planning and definition, preparation, design sessions, and finalization. Tasks for the planning phase are designating the executive sponsor, establishing the need for the system, selecting team members, and defining the scope of the session. Task for the preparation phase are scheduling design sessions, conducting orientation and training for the design session participants, preparing the materials, rooms, and software assistances, customizing the design session agenda, and conducting the kick-off meeting. Tasks for the design session phase are reviewing project scope, objectives, and definition document, identifying data, process, and system requirements, identifying system interfaces, developing a prototype, documenting decisions, issues, assumptions, and term definitions, and assigning responsible person for resolving all issues. Tasks for the finalization are completing the design document, signing off the design documents, making a presentation to the executive sponsor, demonstrating the prototype, obtaining the executive sponsors approval to proceed, and evaluating the JAD process. (Rottmann 2001)
JAD is successful when all team members know the clear meaning of the process. The team should be diverse and include representative of all areas that are affected by the project. Every team member has equal responsibility and decision making power in the group. Also they should participate in JAD meetings, which should be held when there is something substantial to talk about. Even so not more than 3 or 4 weeks should pass between meetings. Benefits that the group gets from using JAD are for example it increases communication, it builds consensus and ownership, improves design quality and generates better solutions, designs cross-functional solutions, helps teams to get focused and to stay focused, and helps to get the right job done and at the right time. (Rottmann 2001)
2.2.2.2
Agile Modeling
Agile Modeling (AM) is a practice-based methodology that enables software-based systems to be modelled and documented. The Agile Modeling methodology is collection of practices which are guided by principles and values. These practices can be applied on a software development project in an agile manner. AM it is not a complete software process, because it focuses on a portion of the overall software process, modeling and documentation. That is why it does not include for example Copyright AGILE Consortium
Page
: 15 of 39
following activities: programming, testing, and project management, and therefore it should be used with another full-fledged process such as XP, DSDM, SCRUM, or UP. (Ambler 2002)
AM has adapted the values of XP, which are communication, simplicity, feedback, and courage, and extended them with adding the fifth value, humility. It is essential to have effective communication between everyone involved in the project, including both developers and project stakeholders, because the primary reason of modeling is to improve communication. Successful modeling also requires the simplest development solution that meets all of the needed requirements and to obtain feedback regarding the models often and as soon as possible. Furthermore, courage is needed for making decision and staying with them, and humility is needed for recognizing that people make mistakes and everybody do not and does not need to know everything, because every member has their own area of expertise and have value to add to a project. (Ambler 2002)
AM is based on a collection of principles. According to these core principles software should be the primary goal and enabling the next effort should be the secondary goal. Travel light advises to create just enough models and documentation to get by, and assume simplicity recommends that the simplest solution is the best solution. Requirements evolve over time so changes should be embraced, and to do that an incremental approach should be taken into account, because then system can be changed in small portions at time instead of massive releases. Furthermore, modeling should be done with a purpose. First, the valid purpose for creating a model should be identified and then the audience for that model should be described. To be effective multiple models should be used because each model describes only one aspect of the software system. Modeling work should be done with quality, and the stakeholder investment should be maximised with the right that the stakeholders can decide where the resources should be invested. In addition to these core principles AM also includes supplementary principles, which are for example open and honest communication, and the content of a model or document should be more important than representation. (Ambler 2002)
AMs core practices are organized into four categories that are iterative and incremental modeling, teamwork, simplicity, and validation. AM defines four practices that support iterative and incremental approach such as apply the right artifact(s), create several models in parallel, iterate to another artifact, and model in small increments. Also AM defines four practices that enable effective teamwork and communication that are modeling with others, active stakeholder participation, collective ownership, and display models publicity. Practices that enable simplicity within modeling are create simple content, depict models simplicity, and use the simplest tools. Testing and validation practices are such as consider testability and prove it with code. (Ambler 2002)
Page
: 16 of 39
2.2.2.3
Rapid Production of Documentation, 7 steps
Rapid Production of Documentation, 7 steps (RaPiD7) is a method for document authoring in software development projects. This method aims at continuous and early information sharing, and committing people to made decisions. With RaPiD7 the outcome is produced in quite short time, decisions are made before anything is written, and all parties are involved early in the documentation. (Kylmkoski 2003)
RaPiD7 defines a three-layer structure: product layer, case layer, and workshop layer. The product layer depicts how human and joint decision-making is planned for software projects. In other words it means identifying the cases for applying RaPiD7. The case layer depicts how the selected cases are created in consecutive workshops. And the workshop layer depicts how the actual work is carried out in the workshops. (Dooms and Kylmkoski 2005)
RaPiD7 is a method in which the documents are written in a team in consecutive workshops. The workshops contain seven steps, which are preparation, kick-off, gathering ideas, analysing ideas, detailed design, decisions, and closing. Purpose of the steps is to provide information on how to organize efficient workshops in software projects. The workshops are planned in detail therefore the preparation step is performed for each of the workshops. The aim is to find out all the needed information to be used in the workshop. This usually requires about two to three days of work for the first workshop and a few hours for the ensuing workshops. The kick-off step is performed in the beginning of the first workshop, and if needed, in the beginning of the ensuing workshops. The purpose is to define a common theme for the participants and to explain the goal of the workshop. The following four steps are performed in a repeatable manner according to a predefined agenda in each of the workshops. First, different ideas concerning the issue are gathered, then these collected ideas are analysed and problems relating to them are solved. Finally detailed design on the selected ideas is made. This means writing down the actual document. After all the above-mentioned steps, decisions on the results are made with help of decision making techniques. The last step, closing, is performed once in each of the workshops to verify the results and to agree on the next steps for example scheduling the following workshop. (Kylmkoski 2003; Dooms and Kylmkoski 2005)
Typically workshops produce documents that can be finalized after the workshop in couple of hours. The success of the workshops depends on selection of the participants. Therefore, participants should be selected carefully and their participation to the workshops should be assured. (Kylmkoski 2003)
Page
: 17 of 39
2.2.3
Model for Agile Documentation
Rpings recommendations for structuring individual documents consist of the following elements: structured information, judicious diagrams, unambiguous tables, guidelines for readers, thumbnail sketches, traceable references, glossary, and document history. These recommendations make documents more accessible to their readers and help authors to write project documents more quickly. Also the well-structured documents are easier to update, and they pave the way for lightweight documents and to an agile documentation process. (Rping 2003) Table 4 presents the model for structuring agile documents according to Rping. The table describes the essential characters for agile documents, their explanation and the advantage, that can be achieved by using them.
Table 4. Model for Structuring Agile Documents. Character Structured information Judicious diagrams Explanation Organizing documents with Advantage Easier access to information Helps
meaningful chapters and sections Offers overviews that are clear and simple, and without much graphical elements Unambiguous tables Offers two dimensional overview where headings should give all the needed information for the reader Guidelines for readers Thumbnail sketches Traceable references Glossary Document history Describes document Provides short descriptions of the documents different sections Using references to documents that are available to readers Explains document Explains versions differences between Enables to follow terms used in the Improves understanding the purpose of the Improves information Enables search Improves getting information quick information getting needed Better understanding of the documents content and improves
communication
development and changes of the document.
Structured information means that documents should be organized with meaningful chapters, sections and maybe subsections. Through this structure readers can access information in a document much easier than if there was not any structure. After well-chosen chapters and sections Copyright AGILE Consortium
Page
: 18 of 39
the structure of the document can be enhanced with building blocks. Each pattern consists of five building blocks which are its title, the problem, the forces, the solutions, and the discussion. This kind of a structure makes it easier for readers to identify which part includes which type of information. (Rping 2003)
Judicious diagrams can offer splendid overviews, while the surrounding text refers to them and explains details to the extent that is necessary. Even though the diagrams complement the text, the document should not be cluttered up with unnecessary diagrams. Generally the best diagrams are the ones that are clear and simple, and include only a small amount of graphical elements. Instead of writing down long lists of details agile documentation prefers to communication. So a diagram is often the best method to do that, because diagrams can get an idea across, a discussion started or improve communication. (Rping 2003)
Tables should be used to present systematic information because tables are clear and direct. Tables are similar to diagrams, but they have two-dimensions, which are represented by the rows and columns. With tables information can be presented in a concise and unambiguous way that helps readers to better understand the documents. The more self-sufficient the table is, the easier it is to understand. In an ideal case, the headings for the rows and columns should give the reader all the necessary information to understand the table, and the surrounding text should give background information what is presented in the table. (Rping 2003)
In software projects people are typically in different roles and have different information needs, so a document can be important for someone and totally unnecessary to someone else. Also people may read the same document with different intentions, and some documents might require that readers have read other document previously or are otherwise familiar with the subject. To solve these problems there should be some short guidelines at the beginning of each document describing the purpose of the document and explaining, how different groups of readers can approach and use the document. (Rping 2003)
In addition to clear structure of chapters, sections, and subsections, quick information search is essential. Readers should be able to browse through a document at a high level, and decide whether they would like to go deeper or whether to move on to the next section. This kind of sequential reading at different levels of detail is enabled with thumbnail sketches that provide short descriptions of the sections of a document. Thumbnail sketches also include the sections general goals and its major ideas. There are two ways of doing thumbnail sketches: section can begin with abstract or summary, or a few paragraphs from each section can be chosen and used as thumbnail sketches.
Page
: 19 of 39
Thumbnail sketches can be easily identified if they appear repeatedly at the same place within a section. (Rping 2003)
A reference to an unavailable document is not useful for readers. Therefore documents should only include references to other documents that readers can obtain without much effort. References can be made to other documents in the same project, and references to documents from other projects are good as long as those documents are available to the team members. References to books and journals can be made if they are considered as the standard literature of software engineering that can be found from most of the organizations libraries. Some scientific publications are not readily available therefore it is not appropriate to make references to such sources. Target readers should be taken into account when making references to other documents, because they affect to the appropriateness of references. (Rping 2003)
Glossarys purpose is to explain technical terms and the terms specific to the application domain. Setting up a glossary is quite simple. First, all specific terms relevant to the document should be listed in the glossary in alphabetical order. And second, a definition or explanation that is understood by the team members should be placed to each entry. Also further information sources can be included in the definition. If glossaries are overlapping because of several documents, that project requires, then it is better to use a central glossary and make references to it from project documents. Also a glossary tool can be considered if a project is really large. The glossary tool is a small database that contains technical terms and terms from application domain. With the glossary tool redundancy between the glossaries of several documents can be managed. (Rping 2003)
The purpose of the document history is to explain the differences to the previous versions of a document, and relate the document to versions of the software it describes. A document history has an entry for each new version, and it is extended as the document evolves. Each entry has a version number for the document, the document status, the author for that version, and a short list of changes that have been made since the last version of the document was released. Also if the document describes actual software, the version of the software to which the document refers should be included in the entry. A document history should be maintained only if the continuing documentation is under consideration because otherwise it is not reasonable. (Rping 2003)
Page
: 20 of 39
3.
RESEARCH DESIGN
This chapter introduces the design context for the research. The research methods are discussed and the agile research setting of the case projects is described. The intention of this research is to find out how agile documentation was created, maintained and structured in three case projects which are uniCorn, Roger and Avalanche. These case projects were software development projects at VTT. The projects were chosen because qualitative information was available and it was possible to make interviews and get the needed information about projects documentation.
3.1
Research Methods
This research is performed as a qualitative research; results of this study are not produced in any way of quantification (Strauss and Corbin 1990). The research is also a case study, which is a preferred method when how or why questions are asked, there is not much control over events which are being researched or the research focuses on a contemporary phenomenon within real-life context. (Yin 1994) This research consists of a literature review and an empirical part, which includes interviews with case project members, support group, steering group, and the customer. Thus the data gathering method was interviewing, because it is a good method for gathering profound information (Hirsjrvi and Hurme 2000). The intention with the interviews was to cover background for documenting in Mobile-D projects. The results from the interviews act as basis for understanding documenting process in Mobile-D projects. Data was also gathered by examining the documents created in the case projects. The literature review consists of scientific publications: books and articles, which were collected from scientific databases, libraries, and Internet.
The method for gathering information in this study was mainly interviewing because it seemed to be the best way for getting information about the case projects and their documentation. The seven interviews were semi-structured and they were carried out as individual interviews (Hirsjrvi and Hurme 2000). The people who were involved in the projects and thus involved in documentation (either making, updating or using the documents) were interviewed, in order to find out for example how the documents were created, how they were used and what kind of possible improvement ideas they have. The interviewees were chosen based on their role in the project. The intention was to get different point of views by interviewing project managers and developers. It was also important that the interviewees were actually involved in the documentation process. Each interview lasted about half an hour. There were two persons performing the interviews, the interviewer and a scribe. Two of the interviewees were project managers and the rest were developers. The questions (Appendix 1)
Page
: 21 of 39
concerned the projects and their documentation: information about background, general information about documenting, and more specific information about documenting in the case project.
3.2
Agile Research Setting in Mobile-D
Mobile-D is an agile development approach for mobile devices, which is based on Extreme Programming (development practices), Crystal methodologies (method scalability), and Rational Unified Process (life-cycle coverage). The ideal case is to have less than ten developers working in a co-located office space. Developers aim at delivering a fully functional mobile application incrementally in several iterations. The development work is divided into different phases that are explore, initialize, productionize, stabilize, and system test and fix. The practices of the different phases include nine principal elements: Phasing and Pacing, Architecture Line, Mobile Test-Driven Development, Continuous Integration, Pair Programming, Metrics, Agile Software Process Improvement, Off-Site Customer, and User-Centered Focus. (Abrahamsson et al. 2004)
In various phases of Mobile-D method different documents can be created and/or earlier made documents can be updated. These phases and possible documents created in them are in detail described in Table 5.
Page
: 22 of 39
Table 5. Possible Documents Created in Different Mobile-D Phases. Phase Explore Initialize Productionize Stabilize System Test and Fix Documents Project plan Initial requirements document Base process description Architecture line description Measurement plan Training plan Software architecture and design description Acceptance test documentation Story and task cards The product documentation is finalized. Final release Found defects System test report Test log
Implemented Release audit functionality Product backlog Developer notes User interface illustrations Acceptance tests checklist Defect list Daily status report Action point list Experience data of the project team
The Explore phase focuses on planning and establishing the incipient project. Therefore, the ground for implementation of the software development product is set. In this phase, created documents could be for example project plan, initial requirements document, base process description, measurement plan, and architecture line description. The Initialize phase focuses on preparing and verifying all critical development issues relating to the forthcoming project. The main goals of initialize phase are to have a good overall understanding of the product for the project team, and to prepare all needed resources, project plans, and all critical development issues. Thus, for example following documents could be created: software architecture and design description document, implemented functionality, product backlog, developer notes, user interface illustrations, and acceptance tests. The Productionize phase focuses on implementing the required functionality into the product. In this phase, created documents can include acceptance test documentation, story and task cards, release audit checklist, defect list, and daily status report. The Stabilize phase focuses on finalizing the implementation of the product, and enhancing and ensuring the quality of the product. The documentation of the product should be finalized in this phase. The System Test and Fix phase focuses on producing error free system by testing the system, providing information of found defects, and fixing the defects. Therefore, for example following documents could be created: final release
Page
: 23 of 39
(tested and fixed system), documentation of found defects, system test report, and test log. (MobileD 2005.)
3.3
Case Description
From projects held at VTT uniCorn, Roger, and Avalanche were depict. These projects were chosen, because of their similarities. Projects were small, meaning that the project teams consisted of four to six persons, from which most were students. All of the projects had same persons in the steering and support groups, and the same person as a project manager in Roger and Avalanche. In all projects Mobile-D method was used and the projects lasted about eight weeks. Because of Mobile-D method pair programming was used in all of the projects. Test Driven Development (TDD) was used in Avalanche but not in uniCorn and in Roger. In Roger TDD was not used because it was not useful to test all the methods, testing would have been too time-consuming, and all the parts of the system were not possible to test at all. In uniCorn TDD was not used because proper tools were not found.
3.3.1
uniCorn
The focus of uniCorn project was to produce a mobile software product for the external customer organization as an extension on their existing software product. At the beginning the development team consisted of six software developers including four Symbian trainees, a Masters student who had previously worked in one of the Mobile-D projects at VTT, and an experienced developer from VTT. After five weeks, some changes were experienced within the project team, because two of the Symbian course undergraduates left the project. Therefore, one new member was added to the project team. This new member was a Masters student, who had previously worked in one of the Mobile-D projects at VTT. Two Masters Thesis students worked part timely, two days per week, and the other three team members worked full-time. In addition, the project team had a support group of seven persons. The project work was done in a co-located development environment. The uniCorn project started third of May and ended forth of August 2004, so the project lasted 4 months. Due to technical difficulties, the uniCorn project was restarted after five weeks at the beginning of June. Altogether, the project comprised of nine iterations, and 5.2 person months were utilized.
3.3.2
Roger
The purpose of the Roger project was to continue the development of the generic Object Viewing Mechanism for MIDP2.0 mobile devices (MIDP-OVM), which can be used for browsing any Naked Objects applications. Another goal of the project was to create mobile application for stockbrokers, Copyright AGILE Consortium
Page
: 24 of 39
Naked Zombie, which was implemented with Naked Objects. The development team of Roger project consisted of four Masters students, and had a support group of two persons. The project team worked in a co-located development environment 24 hours per week for eight weeks. The Roger project started 18th of October and ended 17th of December 2004, so project lasted two months. Altogether, the project comprised of six iterations, and the total effort was 810 hours.
3.3.3
Avalanche
The purpose of the Avalanche project was to implement an agile project management tool to be used via web browser and mobile phone. The software was implemented on MySQL database using Java and Java Servlets on the server side and MIDP 2.0 on the client side. The development team of Avalanche project consisted of six developers including four Masters students and two developers from VTT. In addition, the project team had a support group of nine persons. The project team worked in a co-located development environment 24 hours per week for eight weeks. The Avalanche project extended from October to December 2005, so the project lasted two months. Altogether, the project comprised of five releases.
Page
: 25 of 39
4.
RESULTS
In this chapter the results of the research are discussed. First, the documents created in each project are presented. These documents include project plan, software architecture and design description, which were chosen for closer examination in this research. Then the process of creating certain documents in the case projects is described in timelines. After that, the structure of these document is explained and evaluated according to Rpings document structure features, and the results are presented in tables.
4.1
Documentation in Case Projects
The documents created in three case projects are summarised in Table 6. In all of the case projects the following documents were created: project plan, final report, user interface description, software architecture and design description, acceptance test sheets and task and story cards. Thus in all the phases of the projects i.e. in the phases of the Mobile-D method at least one document was created according to the framework. In addition there were documents related to testing. In uniCorn they were system test report, system test log, release tests and bug list. In Avalanche they were system testing and bug list. Also in Roger and uniCorn there was a document called LOC metrics which includes information about the amount of lines of code. In Roger and Avalanche documentation about coding standards were produced and in Avalanche also documents called personas and database plan were created. In uniCorn there was also an actual document of action points created.
Page
: 26 of 39
Table 6. Documents Created in Roger, uniCorn, and Avalanche Projects. Project Created documents Roger Project plan Final report User Interface description Software architecture and design description Acceptance test sheet LOC metrics Task and story cards uniCorn Project plan Final report User Interface description Software architecture and design description Acceptance test sheet LOC metrics Coding standards System test report System test log Release tests Bug list Task and story cards Action point lists Avalanche Project plan Final report User Interface description Software architecture and design description Acceptance test sheets Coding conventions System testing Release audits Project backlog Database plan Bug list Task and story cards Personas
Based on the interviews some observations were drawn. In the opinion of the project manager of Roger and Avalanche, in Roger the documentation list was more extensive and precise than in Avalanche. This was partly due to the fact that the project team had more time to document and the team was more experienced and skilled. Although in Roger there were no actual documents about requirements, the backlog existed in a flap board. In Roger the bug list was more accurate than in Avalanche, because in Roger there were third-party software and the bugs were described more specifically. It came up in the interviews that in Avalanche in the coding conventions should have been better agreed on; the naming of the variables was not clear enough for some team members.
4.2
Process of Creating Documents
In this subsection the process of creating documents in the case projects is described based on the interviews and the actual documentation. Three documents were chosen from the projects, based on the fact that they could be found in all of the projects. These documents are the project plan, the software architecture and design description, and the final report. Timelines describing the documentation process were drawn of all the projects. The timelines show when these documents were created and updated in the projects. In addition, the releases due dates per project can be seen in the timelines. Copyright AGILE Consortium
Page
: 27 of 39
4.2.1
uniCorn
Of the three selected documents in uniCorn project documenting started with the software architecture and design description on the third of May 2004. The documentation process is described in Figure 1, which was drawn based on the interviews and examining the documents.
Figure 1. Process Timeline in uniCorn.

7.6 Restart R4 14.6 R5 21.6 R6 28.6 R7 5.7 R8 2.8 R9
10.5 3.5.2004
17.5
24.5
31.5
7.6
14.6
21.6
28.6
5.7
12.7
19.7
26.7
2.8 4.8.2004
Project plan
Architecture
Final report
The software architecture and design description was updated frequently, and the latest version was done by the fourth of August. The first version of the project plan was done on the 13th of May and the final version was ready by the 28th of May. The project plan was updated only once during the project. The creation of the final report started on the third of August, and it was finalized on the fourth of August as the project ended. The documents were done in parts during the project. One person was responsible for creating and maintaining a certain document. According to the interview, the whole project team did document templates for the project documentation together, but afterwards person in charge did the updates. During the project, there were un-official reviews for the documents and there were some changes done based on them. In uniCorn less then ten per cent of the whole working time was spent in documenting.
4.2.2
Roger
The documentation process in Roger started as the project began. The more specific information concerning the documentation process can be seen in Figure 2, which was drawn based on the interviews and examining the documents.
Page
: 28 of 39
Figure 2. Process Timeline in Roger.

21.10 R1 4.11 R2 11.11 R3 18.11 R4 2.12 R5 10.12 R6
25.10 18.10.2004
1.11
8.11
15.11
22.11
29.11
6.12
13.12 17.12.2004
Project Plan Architecture Final Report
The first version of the project plan was created on the 18th of October 2004 and the final version was ready by the 10th of December. The project plan was updated after each planning day. The software architecture and design description was done during the fourth and fifth release. It was started after the fourth release on the 24th of November, and the latest version was done by the 8th of December. The creation of the final report started on the 8th of December before the sixth release, and it was finalized on the 10th of December. Thereby the documents were not done at once instead they were updated during the project. The used document templates were the same as in the earlier agile projects held at VTT. Each of these documents had their own person in charge who was responsible for the document, e.g. the project manager took care of the project plan and the final report. Thus the documents were created by one person but the rest of the team had a possibility to review them. Although there were no official reviews for the documents among the project team. Customer reviewed the documents a couple of times but did not give particular change requests. It was estimated that about five per cent of the whole working time went into documenting.
4.2.3
Avalanche
The information concerning the documentation process in Avalanche can be seen in Figure 3, which was drawn based on the interviews and examining the documents.
Page
: 29 of 39
Figure 3. Process Timeline in Avalanche.
6.10 R1
20.10 R2
3.11 R3
17.11 R4
8.12 R5
10.10 3.10.2005
Project plan
17.10
24.10
31.10
7.11
14.11
21.11
28.11
5.12 9.12.2005
Architecture
Final report
The documentation process started a couple of days later than the project begun. The first version of the project plan was created on the sixth of October 2005. The project plan was updated after each release and the final version of it was ready by the 30th of November. The software architecture and design description was started before the second release on the 19th of October, and the second version which also is the latest version was done on the 30th of November. The final report was created and updated at once on the 8th of December. The other documents were done in parts. The document templates were given to the project team by the researchers in the projects steering group. The templates were created based on earlier agile projects at VTT and some of Rpings guidelines for structuring agile documents. All the documents had a person who was responsible for doing a document. There were no official reviews, but the team members checked some of the documents by themselves. From five to ten per cent of the whole working time went into documenting in Avalanche project according to the project team members.
4.3
Structure of Agile Documents
This subsection describes the structure of the three chosen documents in each project. These documents are the project plan, the software architecture and design description, and the final report. The documents were judged based on Rpings (2003) three requirements for an agile documents structure. The requirements are target readers, focused information and document history. They were chosen because these features can be defined explicitly and they can be identified from the documents. With the target readers Rping means, that in a document the group of people to whom the document is directed to are mentioned. Focused information means that a document has an abstract or summary, which explains the focus of the document. Also the title of the document is clear and all sections of the document consist of material which is relevant to the topic. Document history explains the differences to the previous versions of a document, and relates the document to versions of the software it describes. Document history includes a version number Copyright AGILE Consortium
Page
: 30 of 39
for the document, the document status, the author for that version, and a short list of changes that have been made.
The appearance of the requirements in the individual documents were estimated in this study in a scale from A to C in tables 7-9. C means that the requirement can not be identified in the document or it is presented very poorly, B means that the requirement can be identified in the document, and A means the requirement can be identified in the document very well.
4.3.1
uniCorn
Table 7 shows the estimated values for document structure features in uniCorn. In the project plan target readers were not defined. Over all, the information was not valid or reliable in the document, because it was not equal with the information in the final report e.g. tasks were not equal with tasks that were described in the final report. In addition the document had not been approved. Thus, the document did not contain focused information. According to the project plan the document should have been updated after each release, however the document has been updated only once (Figure 2). There were also other weaknesses in the document history e.g. version number of the document did not match with the change history number and the latest version number did not have any comments. Document history was not updated during the project, because it did not include changes that were made during the project.
Software architecture and design description did not include a definition for target readers. Concerning focused information the document did not have any abstracts or summaries, but the titles and the content were specific. Document history had been used in the document. It was updated several times and there were specific comments about the updates.
Target readers were not specified in the final report. Information was not very focused, because quality of the information was not up-to-date and accurate for example it was mentioned that the project started 3.5.2004 and ended 4.8.2004 but according to the final report the final meeting was held 12.5.2004. The document did not give enough background information about the project and what happened during the project, e.g. there was a new start and changes in the project team. The final report was updated a couple of times, but from the second version the comments were missing from the change history.
Page
: 31 of 39
Table 7. Document Structure Features in uniCorn. (C = can not be identified in the document or it is presented very poorly, B = can be identified in the document, A = can be identified in the document very well.) uniCorn Project plan SW architecture & design description Final report
Target readers Focused information Document history
C C B
C A A
C B A
In general, the documents in uniCorn did not have information concerning the target readers. Also the information in all the documents was not up to date and especially the project plan and final report included information which was conflicting. The information was faulty e.g. the dates in the final report were not accurate, and the tasks in the project plan and the final report were not the same. Document history was quite well used, but all the documents were proposals not approved versions.
4.3.2
Roger
Table 8 shows the estimated values for document structure features in Roger. In the project plan the target readers were not mentioned. Concerning focused information there was no summary or abstract, which would have defined the focus of the document. However, the title was clear and the content too. Although the content could have been more informative, there was not a lot information concerning the actual project and the project team e.g. were the team members students or professionals. Document history has been used quite well, only one version numbering misses its comments.
Software architecture and design description included the mention of target readers. However, only one group of people was mentioned, the future developers. The target group could have been defined more specific. Concerning focused information the title and content were clear and the content was also right on the topic. However the references were missing. Document history was defined but one version number was missing from the cover page.
In the final report, the target readers were not mentioned at all. Information was quite focused in the document, meaning that titles and content were well defined, but the document did not include an abstract or a summary. There was also one title without any content. Even so, the document contained enough information. Document history was somewhat deficient: version number was not
Page
: 32 of 39
the same in change history with the current document version, which was mentioned in the cover page. In addition, comments were missing from the latest version.
Table 8. Document Structure Features in Roger. (C = can not be identified in the document or it is presented very poorly, B = can be identified in the document, A = can be identified in the document very well.) Roger Project plan SW architecture & design description Final report
C B A
A A B
C A B
In general, the documents in Roger contained focused information and information about the document history, but target readers were not defined so clearly. All these documents were proposal versions instead of approved versions, which they should have been, because the project had already ended.
4.3.3
Avalanche
Table 9. shows the estimated values for document structure features in Avalanche project. In the project plan target readers were defined. The contents of the document was not checked or updated, because the document included an obvious fault. The information was well focused but it could have been more precise. There could have been more information about the development team, e.g. whether they were students or not. Also all the used hours were not filled in the task table and there were some faults in project dates. Document history was properly used, only the version number in the change history was different with the current document version. The document was not marked as a final version instead it was a to be reviewed version.
In the software architecture and design description the target readers were not mentioned at all. Also the information was not very focused. The contents was not updated, because it included an error. Introduction still included all the guiding for filling the document, and there was only one sentence describing the purpose and content of the document. Thus the document was not reviewed; there is a change that the information is not very valid. According to the interviews it can also be said that the document does not include all the needed information e.g. partly the described program does not work because of the insufficient code. Document history was used in the document a couple of times, but the version number is different from version number in the document history. Also
Page
: 33 of 39
according to the comments in document history this document was a final version, but instead it was a draft version.
In the final report the target readers were not mentioned. Concerning focused information there was one title in the document without any text. The information in the tables was not explained e.g. spent hours in the table named Stories. There could have been also more information about the development team. There was only one version made of the document, so the document was not updated. Also the version was not a final version, instead, it was to be reviewed version.
Table 9. Document Structure Features in Avalanche. (C = can not be identified in the document or it is presented very poorly, B = can be identified in the document, A = can be identified in the document very well.) Avalanche Project plan SW architecture & design description Final report
A B A
C C B
C A B
In general in the documentation of Avalanche document history was used. The only faults were that target readers were not properly defined and in some documents the information could have been more focused. According to the interviews, especially the creating of the software architecture and design description suffered from the lack of time and guiding.
Page
: 34 of 39
5.
CONCLUSIONS AND LIMITATIONS OF THE STUDY
In the agile methodologies, which were chosen for this study, the main emphasize is not on documentation. There are some guidelines for documentation in all of them but the guidelines are not extensive. Scrum and Extreme Programming define some documents which can be used as a base for project documentation. In Scrum documentation consists mainly of different backlogs, which are used for instance for specifying requirements. In XP formal documentation is minimal. The form for documentation are story and task cards, and release and iteration plans. Crystal on the other hand does not define any precise documents. In Crystal documentation is required but it is not determined. The methods for agile documentation offer more extensive guidance. JAD and RaPiD7 tell how individual documents should be written. In both of them, well-structured meetings act as base for making adequate documents. AM on the other hand aims at enabling software-based systems to be modelled and documented.
Concerning the case projects the following documents were created in them: project plan, final report, user interface description, software architecture and design description, acceptance test sheets and task and story cards. There were also documents related to testing and improving the development process. Therefore in all the phases of the Mobile-D framework at least one document was created even though documenting is not the main priority in Mobile-D method. In addition to the list of created documents in the case projects the results also include information about the documenting process in the projects and the structure of the documents. The documenting process and the structure of the documents were evaluated concerning three document, project plan, software architecture and design description, and final report.
The documenting process in the case projects follows the development process, documenting process begins as the project starts. Thus the documents have not been done all at once, in stead they were generally up-dated before the beginning of a new release. Usually the first created document from the three chosen documents in the projects was the project plan. The document templates for the projects were created in earlier projects but they were modified according to a project and its needs. Some person was in charge of a certain document, so mainly the documents were created and up-dated alone, not in teams. However, other team members or support group members helped if it was needed. The development teams did not have any official reviews but in all the projects there was a possibility for each team member to review the documents, because documents were available to everyone. Customers also had the change to review the documents but in all projects they did not use that change. So the participation of the customer in documenting and the review process varied in the projects. Not much time was spent on documenting. In all the Copyright AGILE Consortium
Page
: 35 of 39
projects only about five to ten per cent of the whole working time was used in documenting. Thus the focus was not so much on documenting, and the focus in documenting was more on certain documents, because of the time constrain.
The structure of the documents in the case projects was studied according to three Rpings (2003) document structuring features, which are target readers, focused information and document history. Target readers are intended readers for a certain document and they should be mentioned explicitly in the document. Focused information means that an agile document should have a clear topic and contain only relevant information. This is guaranteed by having an abstract or a summary that explains the focus of the document and a clear title. With the document history the aim is determine the changes between different versions of a document. It also combines the document to different versions of the software it describes. (Rping 2003)
In the documents of the case projects, the target readers were either very well defined or they were not mentioned at all. The documents contained focused information but the information could have been more precise in some of the documents and there could have been more of it. Some weaknesses concerning focused information were detected, e.g. there were some titles without any text under it, information was contradicting between project documents and some tables were not explained in the text. The use of document history in the documents was quite extensive and updates were done quite frequently. In spite of that some weaknesses could be found in them, e.g. some comments were missing and the version numbers were not consistent within the documents. In general it can be said, that the experience and skills of the person who is in charge of a certain document have an effect on the structure of the document. Also support and team work is needed if the development team is not experienced.
The research of agile documentation will continue in the future projects at VTT. Future research areas could include getting more information about agile projects and documentation in them. This could happen by using more case projects. It could be also useful to study other agile projects than just Mobile-D projects. The structure of the documents could be more specifically analyzed to get further information to make more suitable templates for agile projects in general. Concerning MobileD framework, different agile documentation methods, like JAD, AM, RaPiD7, could be applied to find out, how they work together in practice. This way it could be possible to clarify whether the quality of the documents improves by using a certain documenting methodology. The participation of the team members to the documenting process might be different then also. One possible future research area is to find out, how the documenting process has changed during the Mobile-D projects as the methodology has evolved.
Page
: 36 of 39
As limitations for this research, there are few things to notice. There was a time constrain and because of that all the possible material was not used in this research. Thus, there were also more possible case projects and other material for the study than could be used because of lack of time. For example only the project plan, software architecture and design description, and final report from the case projects documentation were chosen for this research. It is good to notice that in the case projects part of the development team was students and their experience and skills can be different than professionals.
Page
: 37 of 39
REFERENCES
Abrahamsson, P., A. Hanhineva, et al. (2004). Mobile-D: An Agile Approach for Mobile Application Development. Companion to the 19th annual ACM SIGPLAN conference on Object-oriented programming systems, languages, and applications, Vancouver, BC, CANADA, ACM Press New York, NY, USA. Agile alliance (2005). http://www.agilealliance.com. Ambler, S. (2002). Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process. New York, John Wiley & Sons, Inc. Boehm, B. and R. Turner (2004). Balancing Agility and Discipline: A Guide for the Perplexed, Addison-Wesley. Briand, L. C. (2003). Software Documentation: How Much is Enough? The Seventh European Conference On Software Maintenance And Reengineering, Benevento, Italy, IEEE Computer Society. Carmel, E., J. F. George, et al. (1992). Supporting joint application development (JAD) and electronic meeting systems: moving the CASE concept into new areas of software development. The Twenty-Fifth Hawaii International Conference, Kauai, HI, System Sciences. Cockburn, A. (2002). Agile Software Development, Addison-Wesley. Cockburn, A. (2005). Crystal Clear: A Human-Powered Methodology for Small Teams, AddisonWesley. Dooms, K. and R. Kylmkoski (2005). Comprehensive Documentation Made Agile Experiments with RaPiD7 in Philips. Product Focused Software Process Improvement: 6th International Conference, PROFES 2005, Oulu, Finland, Springer-Verlag GmbH. Highsmith, J. (2002). Agile Software Development Ecosystems, Pearson Education, Inc. Hirsjrvi, S. and H. Hurme (2000). Tutkimushaastattelu: Teemahaastattelun teoria ja kytnt. Helsinki, Helsinki University Press. Holz, H. and F. Maurer (2003). Knowledge Management Support for Distributed Agile Software Processes. LSO 2002, Chicago, USA. Kylmkoski, R., Ed. (2003). Efficient Authoring of Software Documentation Using RaPiD7. Proceedings of the 25th International Conference on Software Engineering. Portland, Oregon, IEEE Computer Society. Lethbridge, T. C., J. Singer, et al. (2003). How Software Engineers Use Documentation: The State of the Practice. IEEE Software: 35-39. Lippert, M., S. Roock, et al. (2002). Extreme Programming in Action, Practical Experiences from Real World Projects, John Wiley & Sons, Ltd. Lugi, L. Zhang, et al. (2004). Documentation Driven Development for Complex Real-Time Systems. IEEE Transactions on Software Engineering. 30: 936-952. Agile manifesto (2005). http://www.agilemanifesto.org Mobile-D (2005). Mobile-D. Rottmann, D. (2001). "Joint Application Development (JAD)." Rping, A. (2003). Agile Documentation, A Pattern Guide to Producing Lightweight Documents for Software Projects. West Sussex, Jonh Wiley & Sons Ltd. Schwaber, K. and M. Beedle (2002). Agile Software Development with Scrum, Prentice-Hall, Inc. Strauss, A. and J. Corbin (1990). Basics of Qualitative Research, Grounded Theory Procedures and Techniques, SAGE Publications, Inc. Yin, R. K. (1994). Case Study Research: Design and Methods, Sage Publications, Inc.
Page
: 38 of 39
APPENDIX
Appendix 1: Research questions Appendix 1 Background 1. Projects name, size, duration, used methods, and the developed product?
2. Role of the interviewee in the project and in documentation?
General about documentation 1. What agility means in documentation and has it come true in the projects documentation?
2. Basis for documentation (role of documentation)?
3. What documents were created during the project?
4. Was it defined what documents should be done? a. By whom, e.g. customer b. Have defined documents been created?
5. Activities / co-operation with customer (e.g. requirements specification)?
6. Were documentation methods used? a. How were they used?
7. Were any useless documents created (that you did not need)?
8.
Were some other documents needed?
9. In what phase of the project documents were created?
10. In which stages of the project documents were done? a. Who did and which document? b. How were they done (together or alone, all at once or in parts)? c. Were they reviewed? 11. Were beforehand prepared document templates used? Copyright AGILE Consortium
Page
: 39 of 39
d. Where were they gotten? e. What kind was their content? f. Were the templates modified and if they were what was the basis for that?
12. Was version control used?
More specific information about the projects documentation 13. Which documents has the interviewee done?
14. Which documents has the interviewee used?
15. The use of documents during the project in general: a. Who used? b. Which documents and for what purpose? c. How were they used? 16. When using a document; did it include the needed information or were there something which was not needed?
17. Were the documents updated and if they were, how often was this?
18. Were different versions done (document history)?
19. How much time was used in documenting (e.g. percents)?
20. Are the purpose of the document and the people to whom the document is targeted defined?
a. Is there enough information in the document when reading it as a target reader?
21. Is a clear specified subject for the document defined?
22. How are possible follow-up projects and maintenance taken under consideration in documentation (e.g. source code)?
23. Something else about the project and its documentation that comes in mind:

ITEA-AGILE-D2 10 - v1 0

Enviado por

Dados do documento

Descrição original:

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

ITEA-AGILE-D2 10 - v1 0

Enviado por

Direitos autorais:

Formatos disponíveis

Agile Software Development of Embedded Systems Version : Date : Pages : 1.0 2006.03.

Agile Deliverable D.2.10

Agile Documentation in Mobile-D Projects

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Methods for Agile Documentation ..............................................................................................12

Model for Agile Documentation ..................................................................................................17

CONCLUSIONS AND LIMITATIONS OF THE STUDY ...................................................................34

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

SOFTWARE DOCUMENTATION IN AGILE DEVELOPMENT

Challenges in Software Documentation

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Documentation in Agile Software Development Methods

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

a system architecture description, a common domain model and screen drafts

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Methods for Agile Documentation

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Unified Process (UP). (Ambler 2002)

Joint Application Development

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Rapid Production of Documentation, 7 steps

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Model for Agile Documentation

development and changes of the document.

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public

Copyright AGILE Consortium

Agile Documentation in Mobile-D Projects

Version: 1.0 Date : 09.03.06 Status : Final Confid : Public