I think you need both types of documentation, the english and code kind. One thing not mentioned yet, backfilling tests for a legacy system is a great way to fill in the documentation gaps and learn what the system really does... obviously not ideal, but well worth it.
On Wed, Mar 2, 2011 at 6:16 AM, Alan Ridlehoover <[email protected]>wrote: > Actually, tests are useful as documentation to whoever authors them - > developers, testers, or in the case of acceptance tests, customers. (I use > the word customer in the extreme programming sense.) > > It looks like Peter's developers are writing the acceptance tests for their > system in C#, which is hampering their customer's understanding of the > tests. Progratically converting the C# into HTML is a novel way to help the > customer read the tests. In fact, I would argue that it is a lot like > writing FIT tests on behalf of your customer. Ultimately, though, the > customer will not truly use the tests as documentation unless they > themselves are authoring the tests. > > Alan > > Alan Ridlehoover > [email protected] > 206.412.2526 > > On Mar 1, 2011, at 10:29 PM, Peter Gfader <[email protected]> wrote: > > +1 tests serve as documentation (for developers) > > I think they don't serve as documentation *to others than devs* in their > source code form, because tests and their source is normally not easy > "accessible" to others. > But what about if we generate "documentation" in an accessible format and > publish somewhere? (similar like BDD does) > > In my team we generate documentation with a T4 template that clears out all > C# noise and spits out a HTML document. > > 1 test sample that gets converted to documentation > > Feature: OnlyBidFullIncrements > > 1. Lot1 ActualPrice = 50 > Lot1 BidIncrement = 50 > 2. MarketOp Change AuctionState: Catalogued > 3. Anna enters LimitBid: Lot1, 145 > 4. MarketOp Change AuctionState: Active > 5. Bob places Bid: Lot1, 100 > 6. //Note: Anna is getting it for 100, because it is less than 1 bid > increment away > Expect HoldingBidder AndPrice: Anna, Lot1, 100 > > > These tests / HTML documents act as documentation for us (developers) and > when we talk/explain to others (PO and stakeholders)... > > > > >>What contexts are tests as documenation "good"/ "helpful" etc... for? > > > #1 > > >>Learning a new system through tests. > > To me, a system is new if I haven't seen it for a while ;-) > So re-learning how the system works, is another context where they are > helpful.. > I learn what the edge cases are, what expected input is, and which > collaborator the SUT depends on. > > #2 > What about documenting performance goals? > Example: Create an integration test that hits a certain a webpage and > excepts a result in less than 2 seconds. > This test could act as documentation for that performance goal. > > #3 > Usage of an API can be nicely documented through tests as well > > > > > >> * As for learning a new system goes, tests as documentation don't > >>offer historical explanation. For example, the roads not taken which > helps paint the > >>pictue of why the system is the way that it is. > > > Nice idea, but I cant really think of a practical usage. By writing your > tests in a TDD manner, there is not really a road not taken... > > > my 2c > .peter.gfader. > <http://blog.gfader.com>http://blog.gfader.com > > > On Wed, Mar 2, 2011 at 4:14 AM, Frank Schwieterman < <[email protected]> > [email protected]> wrote: > >> I think the point about unit testing vs integration testing is true, >> what you test is what you've documented. So unit tests tell a >> different story then integration tests. >> >> I just wanted to chip in that I do use tests as documentation, but >> not as something I read through. Its a reference I navigate with >> Reflector or Resharper. When I have a question about a method or >> class, I will find references to it in the tests to understand its >> intent and use. >> >> On Tue, Mar 1, 2011 at 8:09 AM, Alan Ridlehoover < <[email protected]> >> [email protected]> wrote: >> > Good conversation. One point I think is missing is this: >> > Unit tests make good documentation for individual methods/classes. But, >> > automated functional/acceptance tests make better documentation for the >> > system as a whole. And, yes, I've seen environments where the Fitnesse >> > tests were the documentation for the system. I've also seen STiQ tests >> used >> > that way (with less success), and WatiN-based NUnit tests (with good >> > success). >> > Alan >> > On Feb 27, 2011, at 8:08 PM, Michael Ibarra wrote: >> > >> > Hi Aeden, >> > I've never seen tests written and organized well enough to serve as >> > documentation (for neither developers nor "the business"). However, I do >> my >> > best to write and organize my tests to be intention revealing. >> > But that's not why I write tests. I write tests primarily because: 1. I >> want >> > to make sure that the code I write works the way it's supposed to, 2. I >> want >> > to make sure that adding new features doesn't introduce any bugs, 3. I >> don't >> > write(and therefore maintain) any more code than is necessary to >> implement >> > the feature. 4. I find that writing my tests first helps me write >> cleaner, >> > more S.O.L.I.D. code. >> > I want other developers to be able to read my tests and understand what >> my >> > code does, but that's just a side effect of well written and well >> organized >> > tests. >> > Anyway, that's my 2 cents. Hope that helps. >> > Mike >> > >> > On Sun, Feb 27, 2011 at 7:13 PM, Aeden Jameson <<[email protected]> >> [email protected]> >> > wrote: >> >> >> >> I'm curious how much stock people on this list put in the idea that >> >> tests serve as documentation. >> >> >> >> -- >> >> Cheers, >> >> Aeden >> >> >> >> Blog : <http://aedenjameson.blogspot.com/> >> http://aedenjameson.blogspot.com/ >> >> Linked In: <http://www.linkedin.com/in/aedenjameson> >> http://www.linkedin.com/in/aedenjameson >> >> Blah Blah Blah: <http://www.twitter.com/daliful> >> http://www.twitter.com/daliful >> >> >> >> -- >> >> You received this message because you are subscribed to the Google >> Groups >> >> "Seattle area Alt.Net" group. >> >> To post to this group, send email to <[email protected]> >> [email protected]. >> >> To unsubscribe from this group, send email to >> >> <altnetseattle%[email protected]> >> [email protected]. >> >> For more options, visit this group at >> >> <http://groups.google.com/group/altnetseattle?hl=en> >> http://groups.google.com/group/altnetseattle?hl=en. >> >> >> > >> > >> > >> > -- >> > ******************************** >> > Michael Ibarra >> > <[email protected]>[email protected] >> > @bm2yogi >> > <http://dev.bm2yogi.com>http://dev.bm2yogi.com >> > >> > -- >> > You received this message because you are subscribed to the Google >> Groups >> > "Seattle area Alt.Net" group. >> > To post to this group, send email to <[email protected]> >> [email protected]. >> > To unsubscribe from this group, send email to >> > <altnetseattle%[email protected]> >> [email protected]. >> > For more options, visit this group at >> > <http://groups.google.com/group/altnetseattle?hl=en> >> http://groups.google.com/group/altnetseattle?hl=en. >> > >> > -- >> > You received this message because you are subscribed to the Google >> Groups >> > "Seattle area Alt.Net" group. >> > To post to this group, send email to <[email protected]> >> [email protected]. >> > To unsubscribe from this group, send email to >> > <altnetseattle%[email protected]> >> [email protected]. >> > For more options, visit this group at >> > <http://groups.google.com/group/altnetseattle?hl=en> >> http://groups.google.com/group/altnetseattle?hl=en. >> > >> >> -- >> You received this message because you are subscribed to the Google Groups >> "Seattle area Alt.Net" group. >> To post to this group, send email to <[email protected]> >> [email protected]. >> To unsubscribe from this group, send email to >> <altnetseattle%[email protected]> >> [email protected]. >> For more options, visit this group at >> <http://groups.google.com/group/altnetseattle?hl=en> >> http://groups.google.com/group/altnetseattle?hl=en. >> >> > > > -- > > .peter.gfader. > <http://blog.gfader.com/>http://blog.gfader.com/ > <http://twitter.com/peitor>http://twitter.com/peitor > > > -- > You received this message because you are subscribed to the Google Groups > "Seattle area Alt.Net" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/altnetseattle?hl=en. > > -- > You received this message because you are subscribed to the Google Groups > "Seattle area Alt.Net" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/altnetseattle?hl=en. > -- You received this message because you are subscribed to the Google Groups "Seattle area Alt.Net" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/altnetseattle?hl=en.
