skills\ft Transcript Agile Documentation Leaming Objectives ‘After completing this topic, you should be able to = distinguish between valid and invalid reasons for documentation on an agile project + determine whether a given document meets the criteria for agile documentation 1. Reasons for documentation Agile project management is driven by value, During planning and development, every decision is made with the customer in mind — hoping to provide customer value at every step. But one thing that can often undermine this ideal is excessive documentation One of the key principles outlined in the Agile Manifesto is to emphasize "working software ‘over comprehensive documentation. This doesn't mean that no documentation is required for an agile project, Instead it encourages an agile team to get its priorities right — providing working software that's of value to the customer is more important than creating documents about the software or project So an agile approach focuses on keeping documentation "light", limiting it only to what's really needed to get the job done. Most agile teams use specific forms of documentation, favoring those that are simple and highly visual. For example, an agile team is likely to use a project backlog, iteration backlogs, user story cards, and burndown and burnup charts. ‘Some stakeholders, project leaders, and even team members may have invalid, or "non- agile”, reasons for wanting to document everything about a project. On an agile team, invalid reasons for generating documentation include managing risk, following a set process, and sharing information among multiple teams. Select each reason for more information about it Managing risk Project stakeholders may think that abundant documentation — such as frequent signoffs and status reports — can help them stay in control of a project's progress and minimize project risk. However, dealing with large volumes of documentation can waste valuable development time. Also, documentation doesn't add to the value of a product for a customer. So from an agile perspective, effort spent generating documents - or generating documents that will change early on in the project - is a form of waste. Following a processPeople accustomed to more traditional project environments may view various types of documents as compulsory for a project, irrespective of whether they add value. They may see creating these documents as part of a set process for managing any project. In an agile context, however, team members should question whether documentation is required and create it only if i's really needed. The focus isn't on following a set project management process but on creating value for the customer as efficiently as possible. Sharing information among teams When multiple teams are working on the same project, project leaders may believe that it's necessary to document everything as a means of sharing information and keeping everyone coordinated. While communication is especially important in a project that involves multiple teams, excessive written documentation can actually hamper communication rather than helping it. ‘To manage risk, an agile team doesn't create large volumes of documentation. Instead, it works closely with the customer throughout development and asks the customer to review the results of each iteration ‘When it comes to multi-team projects, as far as possible, agile teams share information via more interactive means, like regular face-to-face meetings, video conferences, and collaborative online tools, For any project, i's critical to identify the customer's requirements. In a traditional project, requirements identification occurs early on, before actual development work begins. It's an intensive process that involves recording all of the customer's requirements in detail and finalizing these. From an agile perspective, thoroughly detailing requirements early in a project is wasteful for several reasons: + it's too soon for customers to know what they really want at a detailed level, so requirements are likely to change + finalizing requirements early may prevent the addition of new requirements that could add significantly to the value of a product for the customer + requirements documents take a lot of time and effort to create and maintain, and + written documentation is an ineffective way to communicate requirements ‘An agile team with co-located team members and an on-site customer doesn't require highly detailed requirements documentation. Instead it starts a project with complete yet simple descriptions of what's required. Through regular face-to-face communication, developers and the customer continue clarifying the requirements as the project progresses. ‘There are times when more traditional types of project documentation — like written plans or reports - are necessary on an agile project. For example, certain documents may be required by stakeholders or by regulatory bodies, More documentation may be necessary if team members aren't co-located. And documentation may be needed to support product maintenance and future product updates Select each reason why an agile team may generate documentation for more information.Required by stakeholders The stakeholders financing a project have the right to decide what degree of documentation they want. Different stakeholders may request documents to meet their particular needs. When stakeholders’ requests for documentation appear excessive, you can try to convince them to change their minds or reduce their requirements, But in the end, the decision is theirs, because as investors in the project, they make the business decisions about how their money is spent. Required by regulatory bodies The customer's organization and the organization running an agile project may both be obliged to abide by various governmental and industry regulations and guidelines. These may require the generation and archiving of particular types of documents. Even when current regulations don't require these documents, stakeholders may ask that you create them so they're available if the regulations change and they become required. When regulations call for particular documentation, you should study the regulations yourself and find the most effective, efficient ways to meet requirements, without creating excessive documentation. Necessary if team members aren't co-located When agile team members are geographically separated, their need for documentation may be greater. For example, they may be unable to meet in person, or time zone differences may complicate communications. It may also be difficult for geographically dispersed team members to communicate certain types of information verbally, For instance, information like an architectural model may be best communicated in written or diagram form. ‘So when appropriate, you should use documentation to enhance remote ‘communication among physically dispersed team members. Needed to support maintenance and updates The product delivered as the result of an agile project will have a life span stretching into the future. Customers will use it and other individuals may need to maintain and update the product in future. Accordingly, an agile team may need to create documents like user manuals, operations overviews, and technical specifications. Question Categorize each reason for creating documentation for an agile project as either valid or invalid. Options: A. Valid reason B. Invalid reason Targets: 1. To satisfy stakeholders’ requirements 2. To assist physically separated project team members 3. To meet regulatory requirements4, To manage risk 5. To follow standard processes 6. To enable multiple teams to share all information Answer As the project's investors, stakeholders are entitled to decide how much documentation they require. It's valid to use documentation to support and enhance remote communication among geographically dispersed project team members. It may be necessary for an agile team to create certain types of documentation to comply with governmental and industry regulations or guidelines. An agile team manages project risk by collaborating closely with the customer and having the customer review iteration results, rather than by creating detailed risk scenarios and documentation. An agile team should focus on creating value for the customer as efficiently as possible, adapting processes however necessary to do this. It shouldn't generate documentation just to comply with a set process. If multiple teams work on an agile project, they need to share certain information. However, this is best achieved through methods other than written documentation — like regular face-to-face meetings or teleconferencing. Correct answer(s): Target 1 = Option A Target 2 = Option A Target 3 = Option A Target 4 = Option B Target 5 = Option B Target 6 = Option B 2. Crucial documentation Documentation effort varies over the length of an agile project, but several documents are crucial to a project's success. Near the start of an agile project, an agile team invests effort in creating the vision statement, project overview, and important requirements documentation Less documentation is created as development work proceeds, although acceptance testing documents are needed. Near the end of the project, the team works on creating support documentation and user documentation. Graphic Aline graph shows that the most effort is invested in creating documentation at the start of the project. This drops down and then levelsout until the end of a project approaches, when effort is invested in creating support and user documentation. Select each documentation type to learn about it Vision statement A vision statement defines the ultimate goals of a project. It may be included in a document that also summarizes the project's financial and resource cost estimates, potential benefits and risks, and scheduled milestones — although this shouldn't span more than a few pages. The document motivates potential investors to fund the project, and keeps developers focused on achieving the specified goals. For example, part of a vision statement could state that a system “will unify all procurement activities into an attractive, easy-to-use interface, saving the company Up to $3,000,000 within its frst five years of operation and reducing its paper usage by more than two thirds." Project overview A project overview summarizes critical information about a project, such as its vision, technologies, operating processes, and main customer contacts. It also references other important project artifacts, such as system models and source code. The project overview should be just a few pages long. i's important as a starting point for new team members because it tells them what they really need to know to work on the project Requirements documentation Product requirements represent the core of documented project information. A requirements document defines these requirements, summarizing what a system must be able to do and providing relevant user stories, business rules, and user interface prototypes. These requirements will be fleshed out — and new requirements may be added — as a project progresses. Acceptance testing documents Every user story needs associated acceptance criteria, which testers will later use to determine whether the requirement outlined by the story has been met. For example, testing a feature of an inventory management system may involve verifying that once stock of an item is depleted, a notification is generated and the item becomes unavailable in a customer ordering system. Acceptance testing documents specify acceptance criteria, They're necessary because they tell developers whether their work is complete Support documentation ‘Support documentation is designed for those who'll become responsible for supporting a product once it's released. It may include problem escalation procedures, a list of important contacts, a troubleshooting guide, and helpdesk training material User documentationUser documentation may include training material, user manuals, and quick reference cards. It's designed to equip users to use a product and to find answers to their questions about it, without having to call on support staff Help files and user manuals are often created as separate documents. In addition, it's common to integrate online help files and context-specific help information in a software product. Question Match each type of critical documentation to its purpose. Options: A. Vision statement B. Project overview C. Requirements documentation D. Acceptance testing documentation E. Support documentation F. User documentation Targets: 1. Helps secure project funding 2. Gets new team members familiar with a project 3. Identifies a project's core work 4. Indicates when user stories are complete 5. Assists helpdesk staff in resolving user problems 6. Teaches users how to operate the system Answer By defining a project's ultimate goals, a vision statement motivates potential investors to invest in the project. A project overview summarizes a project's critical information — such as its vision, technologies, operating processes, and main customer contacts. It makes it easy for new team members to learn about the project. Critical requirements documentation helps in the planning of a project's core work by defining key requirements. Acceptance testing documents define criteria for verifying that the requirements outlined in user stories have been fully met. ‘Support documentation includes the types of information that helpdesk staff need about a product to provide effective support for end users. User documentation includes help files and training material designed to teach end users how to use a product. Correct answer(s):Target 1 = Option A Target 2 = Option B Target 3 = Option © Target 4 = Option D Target 5 = Option E Target 6 = Option F 3. Guidelines for documentation For documentation to meet agile guidelines, the benefits of creating it have to outweigh the costs, The documentation also has to be focused, lean, and necessary. Select each guideline for more information about it. Benefits outweigh costs The value of a document should outweigh the cost of creating and maintaining it - financially and in terms of time and effort. Accordingly, an agile team should focus on creating only documents that really contribute to the delivery of value to the customer. The team should also keep documents as short and simple as possible, minimizing the time they take to create and update. Focused In an agile project, each document should have a single, clear purpose — and it shouldn't overlap with any other document. Each document should also be tailored for its intended audience, providing only information that this audience needs and in a way that the audience can easily understand. For example, it's appropriate for system documentation intended for developers to include technical terms, whereas user documentation should be written in clear, simple language that's free of jargon. Lean ‘A document is lean if t's simple and concise, and contains just enough information to fulfl its purpose. Keeping documents lean saves time and effort, and helps ensure that the documents are easy to understand, On agile projects, documents should also be created as late as possible - to avoid the need for frequent changes Necessary An agile team should create a document only if it's needed and will contain information that isn't otherwise available or obvious. For example, it's intuitive that a database field called "Em|_addrs" is designed to hold an e-mail address, so this shouldn't be documented. However, the maximum number of characters allowed in that field isn't obvious and so might be documented. ‘As an example, a computer hardware manufacturer has contracted a company to move its helpdesk functions offshore. The team responsible for the project will be using an agileapproach. The project leader compiles a project overview, which will introduce the project to all current and future team members. The project overview meets the crit for agile documentation Graphic The criteria are that the benefits of the document outweigh the costs of creating it and that the document is focused, lean, and necessary. Supplement ‘Selecting the link fitle opens the resource in a new browser window. Learning Aid ‘Access the Project Overview learning aid to review the project overview for the project and consider whether it meets the guidelines for agile documentation. Select each guideline to learn how the example project overview fulfils it. Benefits outweigh costs The cost of creating and maintaining the overview is low because it's short and will be easy to update. Also, the high-level content it includes isn't likely to change during the project, so it won't have to be updated regularly. The only exception is content in the timing section, although this should be quick to update. The benefits of the project overview are significant because it will provide team members with critical information they need to plan and prioritize their work. Focused The overview has just one purpose — to provide team members with critical information about the project. I's written with this audience in mind and doesn't include any extraneous information Lean The overview is lean in that i's short and to the point, and doesn't contain any unnecessary information or repetition. Necessary The timing, scope, and objective sections contain information that the team needs to identify requirements and conduct iteration and release planning. The technologies section includes the critical information that the team needs to use platforms and systems compatible with UNIX. The customer contact section is also Crucial because the team will need to contact the customer regularly to set up meetings and reviews.Question Which statements ini criteria? ate that the documentation for a project meets agile Options: 1. A transaction verification process document contains a version using technical language and a version using basic language 2. Component completion dates are updated once a week to reflect, changing circumstances 3..A document sketching the interface for capturing user information includes a full description of the database underlying the relevant form 4. A short but inspiring vision statement reminds developers of the inspiration behind the product's development Answer Option 1: Incorrect. The document must be focused on one audience. It cannot cater to both customers and technical staff. Option 2: Correct. Schedule information is necessary so that stakeholders know when different parts of the project will be completed. This information is quick to update, and is made relevant by being updated frequently. Option 3: Incorrect. To meet agile criteria, each document should have a single, clear purpose and contain just enough information to fulfil this purpose. In this example, the database description should be left out or - if the team will have to develop the database — be included in a separate document, which could be referenced in the sketch. Option 4: Correct. To meet agile criteria, the benefits of a document have to outweigh the time and effort it takes to create and update it. Such a vision statement is short, doesn't require much updating, and inspires developers to fulfil the product's bigger purpose. Correct answer(s): 2. Component completion dates are updated once a week to reflect changing circumstances 4. A short but inspiring vision statement reminds developers of the inspiration behind the product's development Summary In an agile project, i's considered unnecessary to generate documentation to manage every possible risk, simply to follow standard processes, or to share all information among multiple teams. However, an agile team may need to create traditional types of documentation that stakeholders or regulatory bodies require, to facilitate communication among geographically dispersed team members, and to support product maintenance and future product updates. Documents that an agile team typically creates include a vision statement, project overview, requirements documents, acceptance testing documents, and support and user documentation,For a document to be agile, its benefits should outweigh the cost of creating and updating it It should also be focused, lean, and necessary. (© 2015 Skiloft Ireland Limited