Thank you for your reply. If I want to learn to drive a car, a document that only lists the car's parts and the functions each part performs is not going to be very helpful to me. I could read through the document, and two thirds of the way down I come to the entry for "steering wheel", and then I learn that a steering wheel is what controls the direction the car is going to go. In a separate section, I happen across the term "accelerator", and I learn how to speed up. In a third place, I find the term "brake", and I learn how to slow down. Then I find the term "transmission" someplace else, and I am completely mystified. It's possible to learn from such a document, but it's very difficult.
A book designed to teach an unobservant 15-year-old how to drive a car will begin by explaining the concepts of how a car works. It will explain a bit about how a car works, how an engine burns gasoline, how a transmission connects the engine to the drive shaft, how brakes stop the car, and so on. All in very simple terms. Then it will begin to describe the tasks the driver needs to perform: how to start the car, how to shift into Drive, how to start rolling (carefully), how to stop. Enough information to give the new driver the ability to move gently around an empty parking lot. Then the book will add information about the rules of the road, and how to safely drive when there are other cars on the road. Only after all of this information has been presented would the book present a list of every single part of the car, what its function is, and why the driver might want to use it. That is how a user's manual should be written: a high-level overview of the concepts, a discussion of the steps needed to accomplish simple tasks, followed by an expanded discussion of available steps that a user might or might not want. Clear examples are provided for performing simple tasks, and as the concepts are expanded, the examples are expanded or new ones are introduced. Only then would an exhaustive list of all available choices be presented. By then, the reader hopefully knows enough to be able to use the reference section to expand on the basic knowledge the earlier sections have given him. My question "What do I do after a build failure" was prompted by the fact that the only choice I could clearly understand was to send an E-mail message. Beyond that, I was drowning in information. (NOTE: The following questions are rhetorical, at least until I read through the wiki again.) How do I use a Merge task? What gets merged? How is the output formatted? Where is it stored? Why do I have to use an XML Log Publisher? How do I use the dashboard? (NOTE: That last question is NOT rhetorical. I have not been able to get the dashboard to work, I don't know how the dashboard should work, I don't know how to tell if installation of the dashboard succeeded, and I don't even know the URL I am supposed to use to get the dashboard to work.) What other choices are there besides sending E-mail messages for notifying users of build results? RobR
