📄 extremedocuments.html
字号:
<head><title>Extreme Documents</title></head><body><h1><img src="logo.gif"> Extreme Documents</h1>I can find no other page on this subject, so I'm creating this one. If there is one or more, please connect me to them. (<a href="http://c2.com/cgi/wiki?XpHasWrittenDocuments">XpHasWrittenDocuments</a> also talks about this.)
<p>First, please refresh your memory of <a href="http://c2.com/cgi/wiki?AlistairCockburn">AlistairCockburn</a>'s observation <a href="http://c2.com/cgi/wiki?AlmostExtremeProgramming">AlmostExtremeProgramming</a>. He makes a really great point, though we'll try to refine it here.
<p>From Alistair's story, please hold in mind that XP <em>requires</em> that you have on-site customers, and all the developers very close together. Now let's look at what an Extreme project must document, and what it
<em>might</em> document.
<p><strong>Requirements Documents</strong>
<p>The customer's requirements must be documented in XP, in two forms. First of all, every single requirement that will be worked on must be written, by the customer, on a card: <a href="http://c2.com/cgi/wiki?UserStory">UserStory</a>. Each <a href="http://c2.com/cgi/wiki?UserStory">UserStory</a> is given a priority by the customers. They can change this at any time. Some <a href="http://c2.com/cgi/wiki?UserStories">UserStories</a> are also given a risk rating, or a dependency rating, in a practice we call <a href="http://c2.com/cgi/wiki?WorstThingsFirst">WorstThingsFirst</a>.
<p><a href="http://c2.com/cgi/wiki?UserStories">UserStories</a> are estimated by developers at the time of <a href="http://c2.com/cgi/wiki?CommitmentSchedule">CommitmentSchedule</a>. This estimate is written on the card. It is allowed, but not required, to keep the estimates in a spreadsheet or other document.
<p><a href="http://c2.com/cgi/wiki?UserStories">UserStories</a> are doled out to the developers during <a href="http://c2.com/cgi/wiki?IterationPlanning">IterationPlanning</a> in the iteration where they are to be implemented. When completed, the customer gets the card back. They should keep it.
<p>Finally, customer requirements are documented in another form. Every requirement is represented by one or more <a href="FunctionalTests.html">FunctionalTests</a> that determine whether the program meets the requirement. We would argue that these tests are in fact documentation of requirments with the added feature that they check to see if it's done. Developers use the tests proactively during development to find out whether they're done yet.
<p><strong>Design Documents</strong>
<p>In an ExtremeProject<a href="http://c2.com/cgi/wiki?edit=ExtremeProject">?</a> underway, design is done using the CRC method. The customers may be involved in this if there is a need to feel sure that the developers understand the <a href="http://c2.com/cgi/wiki?UserStory">UserStory</a>. They may also be involved because they are interested.
<p>After a CRC session, XP does not as a matter of course produce a document artifact. Instead, the developer immediately turns to the system and builds what has been designed. XP picks chunks of work that allow this to be done in a couple of days, not weeks or months, which makes it practical (we think sensible) not to build a temporary artifact such as a UML diagram to represent what will be built.
<p><strong>Code Documents</strong>
<p>We comment methods only after doing everything possible to make the method not need a comment. We prefer to clarify the code directly over putting in an explanation of what the code could say it if were better done.
<p>We recommend class comments, but observe that this recommendation is often not followed. On C3 we have detected no suffering due to lack of class comments. If and when we do detect suffering, we'll probably write <a href="UnitTests.html">UnitTests</a> that check classes for non-trivial comments. Since team members are conscientious, they only need a reminder. It should not be necessary to check for quality of comment.
<p>We have written "literate programs", cf <a href="http://c2.com/cgi/wiki?DonKnuth">DonKnuth</a>, and no one has used them. Too bad, really, they were cool.
<p><strong>Reporting Documents</strong>
<p>See <a href="FourVariables.html">FourVariables</a> for a discussion of how we report resources, scope, quality, and time. <a href="PlanningGame.html">PlanningGame</a>, <a href="UnitTests.html">UnitTests</a>, and <a href="FunctionalTests.html">FunctionalTests</a> are also relevant.
<p><strong>Customer-Required Documents</strong>
<p>When the customer wants a document, such as a user manual or a nifty chart for their wall, they write a <a href="http://c2.com/cgi/wiki?UserStory">UserStory</a> that asks for it, and they put it in an iteration. We sign up, estimate, do.
<hr>
What other forms of documents would you like to inquire about?
<p><em>What about policy/procedure documentation? Are things like <a href="http://c2.com/cgi/wiki?UserStory">UserStory</a> and <a href="PlanningGame.html">PlanningGame</a>, etc., which document various things about XP, actually shown to ExtremeNewbies<a href="http://c2.com/cgi/wiki?edit=ExtremeNewbies">?</a> or is it all communicated face-to-face, or some combination thereof?</em>
<p>Face to face and situated. Remember that the practices are constantly evolving, much as the software is evolving, so keeping precise written descriptions of the practices would be counter-productive, so long as everyone has the same understanding of a practice. The pages here should be treated as a starting point. If there are problems, change something, measure the difference, and move on if the problem gets better.
<p><hr>
<p><a href="http://c2.com/cgi/wiki?OtherExtremeDocuments">OtherExtremeDocuments</a> -- <a href="http://c2.com/cgi/wiki?JakeWatkins">JakeWatkins</a>
<p><hr><a href="http://c2.com/cgi/wiki?edit=ExtremeDocuments">EditText</a> of this page (last edited September 24, 1999)<br><a href="http://c2.com/cgi/wiki?FindPage&value=ExtremeDocuments">FindPage</a> by browsing or searching<p><font color=gray size=-1>This page mirrored in <a href="index.html">ExtremeProgrammingRoadmap</a> as of March 31, 2001</font></body>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -