First, you can produce documentation and remain agile, if the customer or the Product Owner requests to have (read is ready to pay for) documentation.
Grow your documentation incrementally and iteratively, as you'll do with code. Test a little , code a little and ... document a little.
I see three ways of doing this : either include the time to write the documentation in the tasks estimation, create documentation specific tasks, or have documentation backlog items/stories.
The risk with the documentation stories is that they may be planned very late, a long time after that have been implemented, so I won't recommend this.
Documentation tasks have the advantage of being visible in the iteration planning, so they should not been forgotten or overlooked.
Agile does not mean "no specs." It mean test and release early and often (but not necessarily to production).
The backlog in Scrum is the "spec." If you don't actually write down and manage the list of features, you WILL lose features, and you will NEVER be able to figure out when the product will be released (won't be able to estimate amount of work left because you have no idea where you are or how much there is left to do). The list of features MUST be managed by someone. The easiest way to do that is to write down everything the product should do (you can get as intricate in the wording and definition as you want) and keep track of what has been completed and what is left to do. How else will you assign work to developers and report status to "management?
I've put a lot of thought on the subject - we work in a Scrum environment, and we've ended up having difficulties to organize the documentation.
What I'm heading to at the moment, though it's quite early so I don't know if it'll pass the long term test, is to use a wiki for the documentation.
Basically, the workflow is the following :
Stories come up in the backlog
Story gets picked up by a programmer
Programmer does the code, and in the DoD (Definition of Done), also has to write some tests against the new functionnality, and has to edit the wiki to add a page for the new functionnality.
The wiki is organized with mediawiki templates, pretty much inspired from mediawiki extensions doc pages, with the name of the functionnality, the version it has been introduced into, anything that can be usefull. The template adds pictos to distinguish between different kinds of features (and of their status).
At the end of the day, the wiki has the great advantage of letting you add the documentation page without being bothered about where or how to put it, but obviously regularly you need someone to come behind and organize the mess.
The important thing to keep in mind, whatever tool you use, is that the developper should write some doc just after the development has taken place (including technical aspects) - and not before, and not months after...
In my view the functional specification is necessary depending on how involved is the tech team with the product and how senior is the team. If the tech team is involved in the product definition you'll definitely need less documentation because there will be less room for assumptions. If you have a team of engineers that are juniors you need a stronger documentation or else things will not be done the way they were defined in the end of the sprints. Also be aware that remote teams need more documentation in the form of functional specs due to the natural barrier of not being close to the stakeholders and product visionaries. Having upfront functional specs is a feature of agile. I saw a lot of tech teams where the tasks where solely described by a user story and quite often I saw those teams failing to achieve the releases and meeting the stakeholder's expectations.
This subject is very broad and there are a lot of opinions but in my view this can be reduced to the fact that the developers should not have to guess the requirements.
In fact I believe that the success and quality of the deliverables is inversely proportional to the number of guesses/assumptions that the developers need to make. I think agility increases with how well specified is something because you will have less mistakes and will spend less time correcting those mistakes.
If creating a Function Spec is a contractual necessity you should think really carefully what goes in it. You could be refused payment if you fail to deliver what you promise in your functional spec.
Unfortunately you're not going to remain very agile if you adopt this process. Does the client really want the same functions for the re-written application? If yes, then why is it being re-written? I'm sure that there a features that are never used.
I would not bother to document the old version. You have a reference already, the application itself. There is no ambiguity in the software.
Document writing is not anti-agile. Designing something without prioritising and getting feedback from your customer is. An important aspect of agile is getting buy in from the customer. If they don't believe it, then the project will have a harder time than it should.
Given I am working on a document
When I select "Save As..."
Then a menu should appear allowing me to choose a name,
and a file type,
and a location in the file system,
and a file should be created in the file system
As already pointed out, Agile does not mean little to no documentation - "working software over comprehensive documentation".
The way I approach documentation is almost to flip things on its head and to consider just about everything part of documentation (including code and unit tests as technical specs). So, a story (or whatever other mechanism you use to divvy up work) describing a business/user requirement should be detailed enough to be estimated by the team doing the work; otherwise, it is incomplete and vague. Further, something I do in my own practice, if the story (or whatever) is estimated to take longer than one working day to fit the team's definition of "done" it should most likely be broken down (this atomizing then compiling eventually leads to pretty extensive documentation, but does not assume as many unknowns as not doing it will - and can lead pretty interesting reuse and pattern revelations).
Example using BDD style requirements:
Given I am working on a document
When I select "Save As..."
Then a menu should appear allowing me to choose a name,
and a file type,
and a location in the file system,
and a file should be created in the file system
We may need/want to add UI elements to accomplish this, menu items, storyboards, keyboard shortcuts, etc. to this description (we may have multiple variations on the same theme of "saving a file"). And so on.
All of these related artifacts can be attached onto the base story/requirement; resulting in more complete documentation. But, only add those stories you actually implement to your documentation of the web version of the software.
Here's where things get kind of flipped on their head and become more "Agile". During development, and after development, revisiting the documented requirement and adding changes/modifications/improvements made by the team edits are made (without having to go through a documentation-only CCB). The ability to edit/update the documentation and related assets without going through all the review boards and whatnot - or throwing the document "back over the wall" when we find out during development that the document is incomplete in some way makes us able to adapt to the unknowns - therefore, Agile.
This documentation should have some form of version control or history, which allows us to describe the system we desired, but also describe the system that was actually implemented - noting another answer/suggestions regarding documentation being part of the Definition of Done (something I also do). (Wikis are good for this; however, a fully integrated concept is a little more desirable - e.g., being able to relate a ticket to a file in trunk in the version control system would be nice.)
To kind of conclude. Creating exhaustive documentation up front, which cannot be altered during and/or shortly after the development effort, will keep you from being agile - able to quickly adapt to unknowns. However, to reference Leading Lean Software Development, wherein they mention that if policies do not allow for certain practices/processes to be used properly, then it doesn't matter if you say you are lean (or scrum, or agile).
One way to make sure you are not being overly exhaustive - probably could've used this mindset on this answer - is to only write what you need to when you need to (similar concepts exist in development in general). Another would be to get everyone to understand that you don't need to try and figure everything out up front (the biggest transition from Waterfall to Agile) - we will document every idea and it may or may not end up in a release. And, finally, deprecate (and remove) anything that no longer applies...I remember seeing documentation for a system once and, when I reviewed the system, half the document didn't actually apply to the system anymore.
Since you have a document describing what the product should do, I would use it as the initial backlog and start splitting the work in bite size pieces ordered from highest to lowest priority. Each set of pieces would then be handled during an iteration. In brief, use Scrum with your initial document as the backlog.
I would not go straight to the implementation without doing this prioritization work. It does not require a lot of writing but more referencing the pieces you want to tackle.
I would not document the whole thing upfront.
In addition, you will have some tasks directly related to the platform your tackling and those tasks need to be captured and added to the sprint backlog.
Also, you may realize that you don't want to implement all the requirements after a few iterations.
Agile has a Functional Specification document in the form of the agile Features list, Product Backlog and even as far into the sprint as tasks in the sprint Backlogs too. The fact they are not called documents doesn't make them any less. And the difference from the Functional Spec in waterfall?...Agile Functional Spec only contains what is required (lol) therefore is less voluminous, remember your "Working software over comprehensive documentation"?
发布评论
评论（8）
首先，如果客户或产品负责人请求提供（已准备好付费）文档，您可以生成文档并保持敏捷性。
增量式、迭代式地扩展您的文档，就像您对代码所做的那样。 测试一点，编码一点，然后......记录一点。
我看到了三种方法：要么在任务估计中包含编写文档的时间，创建文档特定任务，要么有文档积压项目/故事。
文档故事的风险在于它们可能计划得很晚，在实施之后很长一段时间，所以我不会推荐这样做。
文档任务的优点是在迭代计划中可见，因此不应忘记或忽视它们。
First, you can produce documentation and remain agile, if the customer or the Product Owner requests to have (read is ready to pay for) documentation.
Grow your documentation incrementally and iteratively, as you'll do with code. Test a little , code a little and ... document a little.
I see three ways of doing this : either include the time to write the documentation in the tasks estimation, create documentation specific tasks, or have documentation backlog items/stories.
The risk with the documentation stories is that they may be planned very late, a long time after that have been implemented, so I won't recommend this.
Documentation tasks have the advantage of being visible in the iteration planning, so they should not been forgotten or overlooked.
敏捷并不意味着“没有规格”。 这意味着尽早且频繁地进行测试和发布（但不一定要发布到生产环境）。
Scrum 中的积压工作就是“规范”。 如果您没有真正写下并管理功能列表，您将失去功能，并且您将永远无法弄清楚产品何时发布（将无法估计剩余的工作量，因为您已经不知道你在哪里，也不知道还有多少事情要做）。 功能列表必须由某人管理。 最简单的方法是写下产品应该做的所有事情（您可以根据需要获得尽可能复杂的措辞和定义）并跟踪已完成的内容和尚未完成的内容。 您还如何将工作分配给开发人员并向“管理层报告状态？”
Agile does not mean "no specs." It mean test and release early and often (but not necessarily to production).
The backlog in Scrum is the "spec." If you don't actually write down and manage the list of features, you WILL lose features, and you will NEVER be able to figure out when the product will be released (won't be able to estimate amount of work left because you have no idea where you are or how much there is left to do). The list of features MUST be managed by someone. The easiest way to do that is to write down everything the product should do (you can get as intricate in the wording and definition as you want) and keep track of what has been completed and what is left to do. How else will you assign work to developers and report status to "management?
我对这个主题进行了很多思考 - 我们在 Scrum 环境中工作，最终在组织文档方面遇到了困难。
尽管现在还为时过早，所以我不知道它是否会通过长期测试，但我目前要做的是使用 wiki 来获取文档。
基本上，工作流程如下：
该 wiki 采用 mediawiki 模板进行组织，很大程度上受到 mediawiki 扩展文档页面的启发，包含功能名称、引入的版本以及任何有用的内容。 该模板添加了图片来区分不同类型的功能（及其状态）。
归根结底，维基百科有一个巨大的优势，它可以让您添加文档页面，而不必担心将其放在哪里或如何放置，但显然您经常需要有人来整理混乱的内容。
要记住的重要一点是，无论您使用什么工具，开发人员都应该在开发完成后（包括技术方面）编写一些文档 - 而不是之前，也不是几个月后......
I've put a lot of thought on the subject - we work in a Scrum environment, and we've ended up having difficulties to organize the documentation.
What I'm heading to at the moment, though it's quite early so I don't know if it'll pass the long term test, is to use a wiki for the documentation.
Basically, the workflow is the following :
The wiki is organized with mediawiki templates, pretty much inspired from mediawiki extensions doc pages, with the name of the functionnality, the version it has been introduced into, anything that can be usefull. The template adds pictos to distinguish between different kinds of features (and of their status).
At the end of the day, the wiki has the great advantage of letting you add the documentation page without being bothered about where or how to put it, but obviously regularly you need someone to come behind and organize the mess.
The important thing to keep in mind, whatever tool you use, is that the developper should write some doc just after the development has taken place (including technical aspects) - and not before, and not months after...
在我看来，功能规范是必要的，具体取决于技术团队对产品的参与程度以及团队的高级程度。 如果技术团队参与产品定义，那么您肯定需要更少的文档，因为假设的空间会更少。 如果您有一个由初级工程师组成的团队，您需要更强大的文档，否则事情将不会按照冲刺结束时定义的方式完成。
另请注意，由于不接近利益相关者和产品远见者的天然障碍，远程团队需要更多功能规范形式的文档。
拥有预先的功能规格是敏捷的一个特征。 我看到很多技术团队的任务仅由用户故事描述，而且我经常看到这些团队未能实现发布并满足利益相关者的期望。
这个主题非常广泛，有很多意见，但在我看来，这可以简化为开发人员不应该猜测需求的事实。
事实上，我相信可交付成果的成功和质量与开发人员需要做出的猜测/假设的数量成反比。 我认为敏捷性随着指定的程度而增加，因为你会犯更少的错误，并且花更少的时间纠正这些错误。
In my view the functional specification is necessary depending on how involved is the tech team with the product and how senior is the team. If the tech team is involved in the product definition you'll definitely need less documentation because there will be less room for assumptions. If you have a team of engineers that are juniors you need a stronger documentation or else things will not be done the way they were defined in the end of the sprints.
Also be aware that remote teams need more documentation in the form of functional specs due to the natural barrier of not being close to the stakeholders and product visionaries.
Having upfront functional specs is a feature of agile. I saw a lot of tech teams where the tasks where solely described by a user story and quite often I saw those teams failing to achieve the releases and meeting the stakeholder's expectations.
This subject is very broad and there are a lot of opinions but in my view this can be reduced to the fact that the developers should not have to guess the requirements.
In fact I believe that the success and quality of the deliverables is inversely proportional to the number of guesses/assumptions that the developers need to make. I think agility increases with how well specified is something because you will have less mistakes and will spend less time correcting those mistakes.
如果创建函数规范是合同必需的，那么您应该仔细考虑其中的内容。 如果您未能兑现功能规格中的承诺，您可能会被拒绝付款。
不幸的是，如果您采用此流程，您将无法保持非常敏捷。 客户是否真的希望重写的应用程序具有相同的功能？ 如果是，那为什么要重写呢？ 我确信有一些功能从未使用过。
我不会费心去记录旧版本。 您已经有一个参考，即应用程序本身。 软件中没有任何歧义。
文档编写并不反敏捷。 设计某些东西时不考虑优先顺序并从客户那里获取反馈。 敏捷的一个重要方面是获得客户的认可。 如果他们不相信，那么该项目将会遇到比应有的困难。
If creating a Function Spec is a contractual necessity you should think really carefully what goes in it. You could be refused payment if you fail to deliver what you promise in your functional spec.
Unfortunately you're not going to remain very agile if you adopt this process. Does the client really want the same functions for the re-written application? If yes, then why is it being re-written? I'm sure that there a features that are never used.
I would not bother to document the old version. You have a reference already, the application itself. There is no ambiguity in the software.
Document writing is not anti-agile. Designing something without prioritising and getting feedback from your customer is. An important aspect of agile is getting buy in from the customer. If they don't believe it, then the project will have a harder time than it should.
正如已经指出的，敏捷并不意味着很少甚至没有文档——“工作软件胜过全面的文档”。
我处理文档的方式几乎是颠覆一切，并考虑文档的几乎所有部分（包括作为技术规范的代码和单元测试）。 因此，描述业务/用户需求的故事（或用于分配工作的任何其他机制）应该足够详细，以便由执行工作的团队进行估计； 否则，它就是不完整和模糊的。 此外，我在自己的实践中所做的一件事是，如果故事（或其他什么）估计需要比一个工作日更长的时间才能符合团队对“完成”的定义，那么它很可能会被分解（这种雾化然后编译最终会导致相当广泛的文档，但不会假设与不这样做一样多的未知数 - 并且可以导致非常有趣的重用和模式启示）。
使用 BDD 样式要求的示例：
我们可能需要/想要添加 UI 元素来实现此目的、菜单项、故事板、键盘快捷键等（我们可能对同一主题有多种变体） “保存文件”）。 等等。
所有这些相关工件都可以附加到基础故事/需求上； 从而产生更完整的文档。 但是，仅将您实际实现的那些故事添加到软件网络版本的文档中。
这就是事情发生转变并变得更加“敏捷”的地方。 在开发期间和开发之后，重新审视记录的需求并添加团队编辑所做的更改/修改/改进（无需通过仅文档的 CCB）。 编辑/更新文档和相关资产的能力，无需经过所有审查委员会等，或者当我们在开发过程中发现文档在某种程度上不完整时，将文档“扔回墙外”，这使我们能够适应面对未知——因此，敏捷。
该文档应该具有某种形式的版本控制或历史记录，这使我们能够描述我们想要的系统，同时也描述实际实现的系统 - 注意到关于文档是完成定义的一部分的另一个答案/建议（我也做）。 （Wiki 对此很有帮助；但是，更需要一个完全集成的概念 - 例如，能够将票证与版本控制系统中主干中的文件关联起来会很好。）
总而言之。 预先创建详尽的文档，并且在开发工作期间和/或开发后不久无法更改这些文档，这将使您无法保持敏捷性 - 无法快速适应未知情况。 然而，参考《领先的精益软件开发》，其中他们提到，如果政策不允许正确使用某些实践/流程，那么你说自己是精益的（或 Scrum 或敏捷的）并不重要。
确保你不会过于详尽的一种方法 - 可能可以在这个答案上使用这种心态 - 是只在你需要的时候写你需要的内容（一般开发中存在类似的概念）。 另一个方法是让每个人都明白，您不需要预先尝试并弄清楚一切（从瀑布式到敏捷的最大转变） - 我们将记录每个想法，它可能会也可能不会最终发布。 最后，弃用（并删除）任何不再适用的内容......我记得曾经看过一个系统的文档，当我审查该系统时，一半的文档实际上不再适用于该系统。
As already pointed out, Agile does not mean little to no documentation - "working software over comprehensive documentation".
The way I approach documentation is almost to flip things on its head and to consider just about everything part of documentation (including code and unit tests as technical specs). So, a story (or whatever other mechanism you use to divvy up work) describing a business/user requirement should be detailed enough to be estimated by the team doing the work; otherwise, it is incomplete and vague. Further, something I do in my own practice, if the story (or whatever) is estimated to take longer than one working day to fit the team's definition of "done" it should most likely be broken down (this atomizing then compiling eventually leads to pretty extensive documentation, but does not assume as many unknowns as not doing it will - and can lead pretty interesting reuse and pattern revelations).
Example using BDD style requirements:
We may need/want to add UI elements to accomplish this, menu items, storyboards, keyboard shortcuts, etc. to this description (we may have multiple variations on the same theme of "saving a file"). And so on.
All of these related artifacts can be attached onto the base story/requirement; resulting in more complete documentation. But, only add those stories you actually implement to your documentation of the web version of the software.
Here's where things get kind of flipped on their head and become more "Agile". During development, and after development, revisiting the documented requirement and adding changes/modifications/improvements made by the team edits are made (without having to go through a documentation-only CCB). The ability to edit/update the documentation and related assets without going through all the review boards and whatnot - or throwing the document "back over the wall" when we find out during development that the document is incomplete in some way makes us able to adapt to the unknowns - therefore, Agile.
This documentation should have some form of version control or history, which allows us to describe the system we desired, but also describe the system that was actually implemented - noting another answer/suggestions regarding documentation being part of the Definition of Done (something I also do). (Wikis are good for this; however, a fully integrated concept is a little more desirable - e.g., being able to relate a ticket to a file in trunk in the version control system would be nice.)
To kind of conclude. Creating exhaustive documentation up front, which cannot be altered during and/or shortly after the development effort, will keep you from being agile - able to quickly adapt to unknowns. However, to reference Leading Lean Software Development, wherein they mention that if policies do not allow for certain practices/processes to be used properly, then it doesn't matter if you say you are lean (or scrum, or agile).
One way to make sure you are not being overly exhaustive - probably could've used this mindset on this answer - is to only write what you need to when you need to (similar concepts exist in development in general). Another would be to get everyone to understand that you don't need to try and figure everything out up front (the biggest transition from Waterfall to Agile) - we will document every idea and it may or may not end up in a release. And, finally, deprecate (and remove) anything that no longer applies...I remember seeing documentation for a system once and, when I reviewed the system, half the document didn't actually apply to the system anymore.
由于您有一份描述产品应该做什么的文档，我将使用它作为初始积压工作，并开始将工作分成按优先级从最高优先级到最低优先级排序的小块。 然后，每组片段将在迭代期间得到处理。 简而言之，将 Scrum 与您的初始文档一起用作积压工作。
如果不进行优先级划分工作，我不会直接进行实施。 它不需要大量的写作，但需要更多地引用你想要解决的部分。
我不会预先记录整个事情。
此外，您还将有一些与您处理的平台直接相关的任务，并且需要捕获这些任务并将其添加到冲刺待办事项中。
此外，您可能会意识到您不想在几次迭代后实现所有需求。
Since you have a document describing what the product should do, I would use it as the initial backlog and start splitting the work in bite size pieces ordered from highest to lowest priority. Each set of pieces would then be handled during an iteration. In brief, use Scrum with your initial document as the backlog.
I would not go straight to the implementation without doing this prioritization work. It does not require a lot of writing but more referencing the pieces you want to tackle.
I would not document the whole thing upfront.
In addition, you will have some tasks directly related to the platform your tackling and those tasks need to be captured and added to the sprint backlog.
Also, you may realize that you don't want to implement all the requirements after a few iterations.
敏捷有一个功能规范文档，其形式是敏捷功能列表、产品待办事项列表，甚至是冲刺待办事项列表中的任务。 它们不被称为文档这一事实并没有减少它们的存在。 与瀑布中的功能规范有何区别？...敏捷功能规范仅包含所需的内容（笑），因此体积较小，还记得您的“工作软件胜过全面文档”吗？
Agile has a Functional Specification document in the form of the agile Features list, Product Backlog and even as far into the sprint as tasks in the sprint Backlogs too. The fact they are not called documents doesn't make them any less. And the difference from the Functional Spec in waterfall?...Agile Functional Spec only contains what is required (lol) therefore is less voluminous, remember your "Working software over comprehensive documentation"?