Agile/Lean Documentation: Strategies for Agile Software Development
敏捷/精益文档：敏捷软件开发的策略
论文信息
-
论文题目：Agile/Lean Documentation: Strategies for Agile Software Development
-
论文出处：http://www.agilemodeling.com/essays/agileDocumentation.htm#StrategiesForAgileDocumentation
探讨话题
1）主要观点
1）最基础的是沟通而不是文档。
2）只有通过写文档才能达到相应目标时敏捷专家才撰写文档，但是可以找到比写文档更好的方式来达到目标。
3）记录稳定的事物，而不是争辩的事物。
4）对文档开发采取渐进的方法，定期寻求反馈，然后根据反馈采取行动。
5）更喜欢可执行的工作产品，如客户测试和开发人员测试，而不是静态工作产品，如普通旧文档（POD）。
6）您应该了解文档的总拥有成本（TCO），并且必须有人明确地选择进行此项投资。
7）写得好的文档可以有效地支持组织记忆，但在项目期间是一种糟糕的沟通方式。
8）文档应简洁：概述/路线图通常优先于详细文档。
9）有了高质量的源代码和备份它的测试套件，您需要的系统文档就少了很多。
10）尽可能轻装上阵。
11）文档应该还不够好。
12）全面的文档并不能确保项目的成功，事实上，它增加了失败的机会。
13）模型不一定是文档，文档也不一定是模型。
14）文档和源代码一样是系统的一部分。
15）您团队的主要目标是开发软件，其次要目标是支持您的下一步工作。
16）拥有文档的好处必须大于创建和维护文档的成本。
17）开发人员很少信任文档，尤其是详细文档，因为它通常与代码不同步。
18）每个系统都有自己独特的文档需求，一种类型不能满足所有需求。
19）询问你是否需要文档，而不是你是否想要它。
20）对系统文档的投资是一项业务决策，而不是技术决策。
21）仅当您在生命周期的适当时刻需要文档时才创建文档。
22）只在有问题时才更新文档。
2）模型、文档和源代码的关系
3）为什么需要文档？
4）文档和项目成功之间的关系
5）模型什么时候持久化？
6）跟文档相关的问题有哪些？
7）轻装上阵意味着什么？
8）什么时候文档变得敏捷？
9）你需要什么类型的文档？
-
Potential Document Audience Description Advice Valuable Deliverable? Contract models Other Teams A document describing the technical interface to a system or portion of a system. See Introduction to Contract Models Yes Design decisions Developers, Maintenance Developers, Project Managers A summary of critical decisions pertaining to design and architecture that the team made throughout development Question the need for most of this information. Are people really going to care several years from now why you did something?Focus on decisions that are not obvious, which had other reasonable alternatives, or ones where you explored what initially looked like a reasonable alternative that in the end proved insufficient for your needs.The goal of this effort is to avoid needless refactoring at some point in the future or rehashing a previously made decision.Design decisions are often documented throughout other artifacts, such as system overviews and source code, although you may choose to have a separate document when appropriate to the situation. Perhaps Executive Overview/Vision Statement Senior Management, User Management, Project Management A definition of the vision for the system and a summary of the current cost estimates, predicted benefits, risks, staffing estimates, and scheduled milestones.Advanced: Consider including listing of major stakeholder groups, their representatives (if any), and their primary goals. This document is typically used to gain funding and support for your project as well as provide status updates to important project stakeholders who may not be actively involved with your project on a day-to-day basis.Keep it short, ideally a few pages, and consider writing it in point form.Have the courage to make this publicly available to everyone that should have access to it, even when it contains bad news, according to the principle Open and Honest Communication. Valuable interim document Operations documentation Operations Staff This documentation typically includes an indication of the dependencies that your system is involved with; the nature of its interaction with other systems, databases, and files; references to backup procedures; a list of contact points for your system and how to reach them; a summary of the availability/reliability requirements for your system; an indication of the expected load profile of your system; and troubleshooting guidelines. Your operations department often has a standard format for this type of documentation or at least may have good examples from other systems that they can provide you to base your document(s) on. Yes Project overview Developers, Managers, Maintenance Developers, Operations Staff A summary of critical information such as the vision for the system, primary user contacts, technologies and tools used to build the system, and the critical operating processes (some applicable to development, such as how to build the system and some applicable to production, such as how to back up data storage). Also provides references to critical project artifacts such as the source code (the project name in the source code control system is often sufficient), where the permanent models pertaining to the system (if any) are, and where other documents (if any) are. I typically create and maintain this document during development.Keep it short and to the point, I don't ever remember one getting beyond ten printed pages and most are less than five.This document serves as a starting point for anyone new to the team, including maintenance developers, because it answers fundamental questions that they are likely to have.Whenever you first share this document with anyone ask them to keep track of major issues that they were not able to easily resolve using this document, or any misinformation they discover, to provide insight into potential updates for the document.I often call this a "Good Things to Know" document. Yes Requirements document Developers, Maintenance Developers,Users, User Managers This document defines what the system does, summarizing or composed of requirements artifacts such as business rule definitions, use cases, user stories, or essential user interface prototypes (to name a few). Writing a requirements specification early in the life cycle should be seen as a very large risk.XP projects typically favor inclusive requirements techniques such as user stories and CRC cards.RUP projects tend towards more formal requirements artifacts and documentation.Disciplined agile teams capture the majority of their requirements as executable specifications. As a result these teams only need brief overviews of the scope which would be part of the system documentation. In scaling situations, particularly when regulatory compliance, large teams, or geographically distributed teams are an issue Support documentation Support Staff This documentation includes training materials specific to support staff; all user documentation to use as reference when solving problems; a trouble-shooting guide; escalation procedures for handling difficult problems; and a list of contact points within the maintenance team. You will find that your support department often has a standard escalation procedure in place, therefore you will not need to write one, and like the operations department may have standard templates or examples that you can work from. Yes System documentation Maintenance Developers, Developers The purpose of this document is to provide an overview of the system and to help people understand the system.Common information in this document includes an overview of the technical architecture, the business architecture, and the high-level requirements for the system. Detailed architecture and design models, or references to them, may also be included where appropriate. System documentation helps to reduce perceived risk on the project by providing "truck insurance", the assurance that if the development team leaves, or gets hit by a truck[1], that critical information about the project is left behind. Unfortunately this is typically false insurance-if you lose someone(s) then no matter how good the documentation is you have a serious problem on your hands because new people still need to be identified, assigned to your system, and need to learn the system. You're much better off increasing your project's "truck number", the minimum number of people that if you lost them would put your project at risk, by supporting knowledge sharing practices such as Active Stakeholder Participation, Collective Ownership, and Model With Others. Yes User documentation Users, User Managers Your users may require a reference manual, a usage guide, a support guide, and even training materials. It's important that you distinguish between these different types of documents because the way that each one is used varies: one is for quick lookups, one is for discovering about how to work with the system, one is for how to obtain additional help, and one is for training. .I typically base my usage guide and training materials on the use cases for the system -the use cases describe how the actors work with the system, therefore they should be a very good foundation on which to base both of these documents..User documentation should be considered part of the user interface for your system and therefore should undergo usability testing. Yes
10）敏捷专家真的需要创建文档吗，有什么好处？
11) 什么时候你该创建文档？
12）什么时候你该更新文档？
13）有效的交付
14） 模板有什么作用？
15）如何减少文档？
-
C = The percentage of the document that is currently "correct".
-
R = The chance that the document will be read by the intended audience.
-
U = The percentage of the document that is actually understood by the intended audience.
-
F = The chance that the material contained in document will be followed.
-
T = The chance that the document will be trusted.
-
Factor Improvement Strategy C = How correct is the document? Minimize the information contained in the documentSingle source information by capturing it in one place onlyHave more than one person work on the document together (i.e. pair write the document and thereby do inspections in progress)Have shared ownership of all documentation so that multiple people will work on itDocument stable, not speculative concepts R = Will the document be read? Work closely with the audience of the document so that you know what they actually require of it U = Will the document be understood? Take an evolutionary (iterative and incremental) approach to its development so that you gain feedback as to its actual value F = Will the document be followed? Prefer executable specifications, such as customer tests and developer tests, over static specifications such as traditional requirements and design documents. By doing so the specification actually provides value to the audienceCapture high-level information in documentation, not details. When you specify details of how to do something and then hand the document to someone for them to follow, you effectively take all of the joy out of the activity for that person because you've done the thinking for them. What would the motivation be for an intellectual worker, such as an IT professional, to follow detailed instructions? T = Will the document be trusted? Work closely with the audience of the documentTake an evolutionary approach
16）什么时候文档是最好的选择？
17）增加文档敏捷度的最佳实践
260
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
