Xp And Documents
Xp And Documents[Try OneWikiStyle here]
ExtremeProgramming is about producing the software and documentation you need as efficiently as possible. We try to eliminate every activity that is not in support of producing what you need. We try to fill every need in the simplest (least expensive) way that will do the job.
If the program needs a user manual, provide one. If it doesn't, don't. Read about C3's non-user manual: CccUserManual.
Regarding internal documentation, most programs need some. There are various forms: UML diagrams, written documents, TechnicalMemo, and so on.
But there are concerns: with any written form except the source code, there is an implicit need to update the documents when the code changes. This is an expense if you do it, and too often it is not done at all. The result is that the very document that was meant to inform in fact misleads.
What should one do in light of these concerns?
Is the above unclear? Where do readers have concerns or disagree? -- RonJeffries
[The section above added to try to bring order out of chaos. It all came from RonJeffries trying to understand why Betsy felt "interrupted" by discussion of why XP thinks documentation is a bad idea.]
(from MissingWikiBeforeXp) "That's the way I feel about XP. I am irritated when I can't talk about how to document software without being interrupted by a discussion of why XP thinks documentation is a bad idea. -- BetsyHanesPerry"
Betsy, pardon me for interrupting, but would you be so kind as to point to a page where one of the XP people says that documentation is a bad idea? I can't find one, but if I can, I'll fix it, because that's not what we think. Thanks! -- RonJeffries
Look at your original contribution to TooMuchDocumentation. You softened it in a later edit, but can you see why I reached the conclusion I did? -- bhp
Please help me understand. I thought I reported factually that I'd never had the problem of too little, had often written docs that never got used, drew no conclusion at all, and asked for counter-experience. Where did I screw up? -- rj
If I say to you, in casual speech, "I've never regretted not buying a Ford", you would naturally infer that I didn't like Fords. Otherwise, I'd have said something like "I really love that Chrysler I just bought." If you say to me, on the Wiki, "I've never regretted the lack of documentation", I infer that you don't find documentation valuable.
Let me give you an example. I loathe troff. However, I have, in my checkered past, repeatedly regretted not being a troff expert. This doesn't mean that I found it worth the effort to learn troff thoroughly; it rather means that I can think of places where the expertise would have been most useful.
Let's take this into formal logic.
You said:
For all situations in my experience, there is no situation such that there was a document that I wanted but did not exist.
I know that you have a wide background. I know that my own wide background includes many projects which had no documentation at all. I assume that yours does the same.
If you say that you have never, on any of those projects, found one case where you wished there were a document, I think it's an entirely defensible inference that you don't think documentation is a good idea.
Thank you Betsy, for trying a second time, I think I sort of understand now. I don't yet know what I'll do about my understanding.
[Revised] What I said there was "I have never suffered for lack of a document". I may have wanted one, probably wanted even more to talk to the programmer. I don't consider this to be hair-splitting. It's definitely nice to have a document that gets you into what the program does - but in my experience, it's the code that tells. And clear code, with comments for getting one in, would be better than a separate document IMO.
[Revised I remain very sure that I would prefer having the program be clear to having a separate clarifying document about it.
In formal logic, "Ron has never seen X" does not imply "Ron does not believe X". I have never seen a giraffe in the wild. Have you? As far as I know, there might be some. -- Ron
But that statement lives in a different context, outside your expertise. Saying "In my X years of software, I have never seen a context where a goto was required" is very different from saying "In my X years of software, I have never seen a giraffe." When you're talking about your domain of expertise, saying that you have never needed a tool, a discipline, or a method is an inherently powerful statement.
[Inserted] Thanks for noticing. I do think that there are several ways of, um, storing information about the software, that are better than conventional software documentation. I don't recall interrupting any of your pages and throwing them off track, but if I have, I apologize and certainly won't do it again. -- rj
In 18 years as a technical writer, I have never used a thesaurus.* What do you immediately infer about my bookshelf?
(*not precisely true; I use one when trying to find product names.) Well, logically I don't know that you don't have one, your husband might have given you one as a gift. I could tell from your writing and your assertion that you don't need one.
Anyway, I'm certainly accepting that what seems to you to be implied/inferrable isn't what I'd have said was. Just haven't worked out what to do about it. Thanks again ... I'll keep on it. -- rj
-- bhp
Here are some other cites:
Kent Beck:
Design documentation is a tougher sell, but again I never said you shouldn't have design documentation. However, communication is the purpose of such documentation and there are better (cheaper, faster, more effective) ways to communicate. Like storytelling, the product of 20,000 years of evolution. And tests (which are even better to write before hacking than documentation). And you'd never let a mediocre programmer code alone, so the problem isn't so bad as it might otherwise be. And...
Which I would summarize as "I never said you shouldn't have design documentation, but I think there are better ways to communicate than using design documentation." Am I being unfair?
Well, I feel that it is a bit unfair, in that you've kind of inferred a meaning which is not supported by the body of work describing XP. We do believe that in XP-able projects, some forms of documentation (writing stories on cards, embedding requirements in tests, writing very clear code) communicate more effectively than other forms such as (big combined requirements documents, code inspection, comments in every method).
A thing that happens here sometimes (and you have NOT done this, I'm just sensitive this week) is that some folks jump on us for things we aren't really saying. So I've learned that we have to do a much better job of expressing what we actually do and believe. That's why I asked, and I'm sincerely grateful for your helping me see how what has been written has been read. Thanks! -- RonJeffries
It seems to me that if you have a non-XP project, with lots of CodeOwnership, remote staff, no customers available, no UnitTests, no PairProgramming, and if for whatever reason you are not going to switch to XP, then you need more documentation than an XP project and it makes sense to discuss how to do it. And comments that assume an XP context aren't very relevant to this other context. -- DaveHarris
Tests and code, no matter how clear, are NOT documentation. Documentation is stuff that is written for the sole purpose of describing your system to humans. The comments in the code could be considered documentation, but you try to get rid of them, too. Ron, it sure seems to me that you are saying that you want to have as little documentation as possible, preferably none. I understand what Betsy is saying perfectly. What I don't understand is why you first say that you want to have as little documentation as possible, and then get bent out of shape when people say that you think that documentation is a bad idea. Be proud of your extremeness! -- RalphJohnson
Wasn't aware that I was bent, Ralph, though I am, of course, twisted. I'd enjoy debating in an alcoholic haze whether source code is documentation or not. What else could it be?
I try hard to say what I think, and not to say what I don't. So I'm troubled when conclusions are drawn from reading that were not premises when I wrote.
I do want to have as little documentation as possible, which is entirely different in my mind from thinking it is bad. I think it's good, but expensive. I think it's good, but too often not current. I think it's good, but too often unused. I think it's good, but too often inappropriate to its audience. I think it's good, but a distant second to a conversation. So I'd do everything within my power to do something other (and better) than documentation - then do a good job of documenting what still needed it. -- RonJeffries
So in the matter of "thinks or asserts there is too much / too little / not enough documentation", we first have to get a common definition of "thinks", "asserts", "is", "too much", "too little", "enough" and "documentation". Sounds like resolving this issue will take a long time... -- AlistairCockburn
"Depends what your definition of "is" is." But maybe not. Mostly, I'm just learning here why Betsy felt that XP thinks documentation is a bad idea when that is not what we actually think. And thinking about how better to express things to avoid such problems in the future. I'm prepared to posit that we have similar definitions to those words, and to discover the differences as we go. This time, however, I discovered that my understanding of formal logic was faulty: I do not regret that I have never had a Ferrari, but I like them a lot. I remain pro-documentation and pro-Ferrari, and somewhat confused as how better to express these feelings more effectively. -- RonJeffries
The code is the documentation... for the programmer. The code is not the documentation for a non-programmer. The question is, to my mind, one of what audience you are addressing. A non-technical audience can't be expected to read source code and understand it. They may be able to read a specifications document and understand it.
As Ron points out, the aim is not to generate piles and piles of documents. It is to communicate to the necessary parties in as efficient a manner as possible. XP makes the point that the most efficient manner of communicating to the developer is the code. It also makes the point that the most efficient manner of communicating to the customer is to have the customer on-site, to talk to them, and to give them regular releases so they can see the final product.
There may be other audiences to talk to besides the developer and the customer. As an example, you may have to communicate to government regulators, or to the customer's board of directors. Other means of communication besides those covered above may be more efficient.
As for XpAndDocuments, from what I can tell, the main point that XP makes is that the development process does not require any long-lived document entities (whilst requiring numerous short-term ones, such as StoryCards). If you have other communication requirements beyond the bare minimum that XP presents, XP suggests that you recognize that fact and schedule the requirements into the PlanningGame as CustomerStories?. -- RobertWatkins
See DontPlanDesigns
The one problem I see at XP is the explicit demand for lack of code documentation. Well-written code needs no additional docs. In many years of doing SW engineering, I have often heard of this myth. Self-documenting Code used to be the buzzword and in reality it never worked out well. More or less an excuse for laziness. Perhabs in Smalltalk, where a method consists of only a few lines of code, this is not as bad as in C++. But one should not forget that many programmers have only mediocre abilities and for them documenting before hacking is a good way to get them to write clearer and better structured code. -- ThomasFunke
I have never met a "mediocre" programmer who could document even as well as he could program. If he can't think clearly enough to express something in a precise language like C++, he probably can't express it clearly in English either. I suppose that having them documenting would keep them out of the code, but that doesn't seem to be the intent here. -- RonJeffries
There are two questions here: method-level comments and design documentation.
I never said you shouldn't write method-level comments. I said you shouldn't have method comments that are totally redundant. And there is a very natural stepwise process that leads you to make nearly all method comments totally redundant.
Design documentation is a tougher sell, but again I never said you shouldn't have design documentation. However, communication is the purpose of such documentation and there are better (cheaper, faster, more effective) ways to communicate. Like storytelling, the product of 20,000 years of evolution. And tests (which are even better to write before hacking than documentation). And you'd never let a mediocre programmer code alone, so the problem isn't as bad as it might otherwise be. And...
It is certainly not true that there is nothing besides the code. That's too simple to possibly work. There are the tests. There are the people who understand and know how to tell stories. There is the metaphor, which everyone understands. And the code does a lot more work than you might imagine it could, besides. But never alone. That would be stupid.
-- KentBeck (it wasn't exactly a question, so I don't mind commenting)
For me, refactoring is a key element in making the code clearer. If people had tried self-documenting code without refactoring, there is no chance of succeeding. The only way you could succeed is if you got it right first time and never needed to change it. -- MartinFowler
XP does NOT demand that there be no code documentation. XP lets you succeed with little code documentation. But that is the result, not the starting point. Yes, tests and user stories are documentation. Yes, user stories are a form of use cases. I think Kent picked the term "user stories" because he wanted something that didn't sound like a software term. -- RalphJohnson
See ExternalDocumentationAndExtremeProgramming
EditText of this page
(last edited April 27, 2006)
or FindPage with title or text search