敏捷开发需求⽂档_需求的长期，敏捷⽂档重庆苇子
敏捷开发需求⽂档
In my training cours, we discuss many topics. Including: how do you document requirements in the long term, in an agile environment?哈佛图书馆
在我的培训课程中，我们讨论了许多主题。 包括：如何在敏捷环境中长期记录需求？
Documentation is stored knowledge. As things are forgotten, its value increas over time. That’s why I think the question of long-term documentation is interesting.
⽂档是存储的知识。 随着事物的遗忘，它的价值会随着时间⽽增加。 这就是为什么我认为长期记录问题很有趣。
I’d like to start with two options for long-term documentation that don’t make n in an agile environment. Then I’d like to point out nsible options. Each with advantages and disadvantages.
白磷化学式>东方山风景区
我想从长期⽂档的两个选项开始，这些选项在敏捷环境中没有意义。 然后，我想指出⼀些明智的选择。 每种都有优点和缺点。
不是有⽤的选项：详细的前期规范 (Not a uful option: Detailed up-front specification)
It does not make n to specify all requirements in detail in advance. In a complex environment, there are frequent changes. Requirements are re-prioritized. This is one of the advantages of agile development. Some requirements are considered, but never implemented. Or not as planned, becau you gain new knowledge during development.
事先详细指定所有要求没有意义。 在复杂的环境中，经常进⾏更改。 需求被重新排序。 这是敏捷开发的优势之⼀。 考虑了⼀些要求，但从未实施。 是否按计划进⾏，因为您在开发过程中会获得新知识。
Discussion and documentation of a requirement costs time. If the requirement is not implemented as documented, it was a waste of time. Time that is urgently needed in development.匹夫是什么意思
讨论和记录需求会花费时间。 如果未按⽂档要求实施要求，那将是浪费时间。 开发中迫切需要的时间。
也不是⼀个有⽤的选择：积压 (Not a uful option either: The backlog)
Let’s say you start to work in an agile way. Maybe you think: there isn‘t any detailed specification. B
ut a backlog. Let’s u it to document the requirements on a long-term basis.
假设您开始以敏捷的⽅式⼯作。 也许您认为：没有任何详细的规范。 但是积压。 让我们⽤它来长期记录需求。
But a backlog rves the future, not the past. It’s more like a to-do list. What do we implement next? The backlog isn't a nsible option for long-term documentation. It doesn’t document what has already been implemented.
但是，积压的订单是为未来⽽不是过去服务的。 它更像是⼀个待办事项清单。 接下来我们要实现什么？ 对于长期⽂档⽽⾔，积压不是明智的选择。 它没有记录已实施的内容。
选项1：实施后存档⽤户故事 (Option 1: Archive ur stories after implementation)
In a training cour, a participant told me that his company manages ur stories in JIRA. And the developers archive them after implementation. Of cour, you can arch this archive. The participant reported that it worked well for them.
在培训课程中，⼀位参与者告诉我他的公司在JIRA中管理⽤户故事。 开发⼈员在实施后将其存档。 当然，您可以搜索此存档。 参加者报告说，对他们来说效果很好。
An agile pragmatist can hardly disagree. What works, works. At least in a certain context. I e 2 risks of this approach:
敏捷的实⽤主义者⼏乎不会不同意。 什么有效，有效。 ⾄少在某些情况下。 我看到这种⽅法有两个风险：
Too many details: In order to be able to u the stories in the long term, you certainly have to document many details.
What if the details cannot be implemented as planned? Will the ur stories be adjusted afterwards? The stories may no longer document the implementation correctly.
太多细节：为了能够长期使⽤故事，您当然必须记录许多细节。 如果细节⽆法按计划实施怎么办？ ⽤户故事会在以后进⾏调整吗？ 这些故事可能不再正确地记录实现。
Delta documentation instead of system documentation: Ur stories describe what needs to be done. The “delta”
from one state to another state. In order to find out the current state, it may be necessary to analyze veral past ur stories. Stories lack context information. They are not system documentation, but
only small fragments.
Delta⽂档⽽不是系统⽂档：⽤户案例描述了需要做的事情。 从⼀个状态到另⼀状态的“增量”。 为了找出当前状态，可能有必要分析⼏个过去的⽤户故事。 故事缺少上下⽂信息。 它们不是系统⽂档，⽽是⼩⽚段。
选项2：系统⽂档的增量调整 (Option 2: Incremental adaption of the system documentation)
The documentation can be maintained continuously. During a Scrum Sprint, you document the current state. The requirements that have just been implemented. The documentation grows over time. It is supplemented incrementally.
该⽂档可以连续维护。 在Scrum Sprint期间，您记录当前状态。 刚实施的要求。 该⽂档随时间增长。 逐步补充。
If you follow this approach consistently, it has a great advantage. The system documentation is always up to date. It documents which requirements have actually been implemented.
如果您始终遵循此⽅法，则将具有很⼤的优势。 系统⽂档始终是最新的。 它记录了实际上已经实施了哪些要求。
One challenge with this option is discipline. Only if you document consistently, the documentation will remain up-to-date. And that costs time.
使⽤此选项的⼀个挑战是纪律。 仅当您始终记录⽂档时，⽂档才会保持最新状态。 这会花费时间。
Moreover, not every developer is a born documentation writer. If, however, the developers do not document themlves,
but instead delegate it to other employees, then there is a risk of information loss.
⽽且，并⾮每个开发⼈员都是天⽣的⽂档编写者。 但是，如果开发⼈员不记录⾃⼰，⽽是将其委派给其他员⼯，则存在信息丢失的风险。
One way to promote this discipline within a team is to put it into the Definition of Done. Something like: “System documentation has been updated”. To be checked in Sprint Review.
在团队中促进这种纪律的⼀种⽅法是将其纳⼊“完成的定义”中。 诸如：“系统⽂档已更新”。 在Sprint Review中检查。
选项3：代码内的要求 (Option 3: Requirements inside the code)
资源英文
A completely underestimated type of long-term documentation is the code of the software. If you structure code appropriately and u naming conventions, you can generate documentation from the code.
完全被低估的长期⽂档类型是软件代码。 如果适当地构造代码并使⽤命名约定，则可以从代码⽣成⽂档。
To realize this, I have . With it you can specify executable U Ca models in the code. They act . Here is a code example
for a U Ca for a credit card:
为此，我 。 使⽤它，您可以在代码中指定可执⾏的⽤例模型。 它们的⾏为 。 这是信⽤卡⽤例的代码⽰例：
Model model = Model.builder()
.uCa("U credit card")
.basicFlow()
.step(ASSIGN).ur(requestsToAssignLimit).system(assignsLimit)
.step(WITHDRAW).ur(requestsWithdrawal).system(withdraws).reactWhile(accountOpen)
.step(REPAY).ur(requestsRepay).system(repays).reactWhile(accountOpen)
.flow("Withdraw again").after(REPAY)
.step(WITHDRAW_AGAIN).ur(requestsWithdrawal).system(withdraws)
.step(REPEAT).continuesAt(WITHDRAW)
.flow("Cycle is over").anytime()
.step(CLOSE).on(requestToCloCycle).system(closCycle)
.flow("Assign limit twice").condition(limitAlreadyAssigned)
.step(ASSIGN_TWICE).ur(requestsToAssignLimit).system(throwsAssignLimitException)
.flow("Too many withdrawals").condition(tooManyWithdrawalsInCycle)
.
step(WITHDRAW_TOO_OFTEN).ur(requestsWithdrawal).system(throwsTooManyWithdrawalsException)
.build();
The documentation follows.
的⽂档如下。
GENERATED DOCUMENTATION - START
⽣成的⽂档-开始
使⽤信⽤卡 (U Credit Card)文明施工方案
基本流程 (Basic flow)
Assign limit : Ur requests to assign limit. System assigns limit.Withdraw : As long as account open: Ur requests withdrawal. System withdraws.Repay : As long as account open: Ur requests repay. System repays.
分配限制 ：⽤户请求分配限制。 系统分配限制。 提款 ：只要开户：⽤户要求提款。 系统退出。 回
报 ：只要户⼝不限：⽤户请求偿还。系统还款。
再次提款 (Withdraw again)
女性瘦腿After Repay:Withdraw again : Ur requests withdrawal. System withdraws.Repeat : System continues at Withdraw.
退款后： 再次提款 ：⽤户要求提款。 系统退出。 重复 ：系统继续退出。
周期结束 (Cycle is over)
Anytime:Clo cycle : Handles RequestToCloCycle: System clos cycle.
随时： 关闭周期 ：处理RequestToCloCycle：系统关闭周期。
分配限制两次 (Assign limit twice)
Anytime, when limit already assigned:Assign limit twice : Ur requests to assign limit. System throws assign limit exception.
任何时候，如果已经分配了限制 ： 两次分配限制 ：⽤户请求分配限制。 系统抛出分配限制异常。
提款太多 (Too many withdrawals)
Anytime, when too many withdrawals in cycle:Withdraw too often : System throws too many withdrawals exception.
任何时候，当循环中的提取次数过多时 ： 提取次数过多 ：系统抛出过多的提取异常。
GENERATED DOCUMENTATION - END
⽣成的⽂档-结束
The same code controls the application behavior and is the source for the documentation. The advantage is obvious: You can generate documentation with little effort. And it reflects the actual behavior of the software.
相同的代码控制应⽤程序的⾏为，并且是⽂档的来源。 优点是显⽽易见的：您可以轻松⽣成⽂档。 它反映了软件的实际⾏为。
Of cour, this approach also requires discipline. Especially on the side of developers. Before using any approach, you should try it out. Is it suitable for the type of software being developed?
当然，这种⽅法也需要纪律。 特别是在开发者⽅⾯。 在使⽤任何⽅法之前，您都应该尝试⼀下。 是否适合正在开发的软件类型？
In addition, you can’t achieve completeness with such an approach. For example, you can’t generate quality
requirements like robustness from the code. Design trade-offs are not part of the code either.
此外，使⽤这种⽅法⽆法实现完整性。 例如，您⽆法从代码中⽣成质量要求，如健壮性。 设计权衡也不是代码的⼀部分。
I am looking forward to your feedback. Which options for long-term documentation do you u?
期待您的反馈。 您使⽤哪些长期⽂档选项？
This article was first published on in German. If you want to keep up with what I'm doing or drop me a note, follow me on , or . Or visit my .
本⽂最初以德语发布在上。如果您想跟上我的⼯作或给我 ，请在 ， 或上关注我。或访问我的 。
敏捷开发需求⽂档
