docs.mbunit.com stage 3 complete
About five months or so ago, I logged a few bugs about the documentation for MbUnit [http://www.mbunit.com/]. I also created a couple of simple project templates for MbUnit and nUnit [/SimpleTDDVisualStudioTemplates]. It was easy enough to do and I ended up chatting to Andy Stopford [http://weblogs.asp.net/astopford] a bit about writing a book on MbUnit [http://www.mbunit.com]. Nothing has happened with that yet, but instead Andy asked me to try and wrestle the current MbUnit documentation into some sort of shape. About the same time, there was a thread or two of discussion dismissing any open source project’s hopes of having a decent set of documentation that wasn’t the source code itself [http://codebetter.com/blogs/scott.bellware/archive/2007/04/11/161702.aspx]. As I’m all about the docs and fancied a challenge to prove that it could be done, I accepted and today, I’m happy to announce that we’ve launched the first iteration of docs.mbunit.com [http://docs.mbunit.com], our online and downloadable documentation for MbUnit v2.4. Please note the emphasis on the word first. We’ve still a long way to go.
Here’s where things stand. MbUnit has several sources of documentation. The wiki on mertner.com [http://www.mertner.com/confluence/display/MbUnit/Documentation] is the main one, then there are the comments in the source code itself, and finally, the many blog posts out there [http://www.mbunit.com/Blogs.aspx] that you all write from time to time. Our first task is to merge those into something a bit easier to find, read and refer to. Then we can go on to be more creative. We’re using Sandcastle [http://msdn2.microsoft.com/en-us/vstudio/bb608422.aspx] and DocProject [http://www.codeplex.com/DocProject] to create docs.mbunit.com. These are the defined milestones so far.
- Get DocProject and Sandcastle generating something we can work with. Ben Hall [http://blog.benhall.me.uk] did some sterling work on this. See his notes here [http://blog.benhall.me.uk/2007/07/sandcastle-and-docproject.html] and here [http://blog.benhall.me.uk/2007/07/sandcastle-docproject-and-creating.html] for more. 2. Run through the wiki and divide the text between the stuff that can be folded back into the source code and thus generated automatically through sandcastle and the stuff that can’t (user stories) which must be updated and pushed out as custom topics. 3. Push out initial story docs and unedited API reference for all to see and initial feedback. (We are here right now.) 4. Clean up the XML comments in the MbUnit.Framework assembly. This is the main area for MbUnit’s class, method and assembly decorators and asserts too [http://temp.mbunit.com/html/WhatDoYouWantToTest.htm] so it gets priority. 5. Complete the story docs migration from the wiki covering test scenarios like using the RowTest [http://www.mertner.com/confluence/display/MbUnit/RowTestAttribute] and Combinatorial test [http://www.mertner.com/confluence/display/MbUnit/CombinatorialTestAttribute] together with any other stories suggested by you. Include stories for scenarios not on the wiki. For example, using the .NET 2.0 RollBack2 attribute or the GrammarFixture test. 6. Discontinue the mertner wiki.
Pushing out the API docs unedited with only four of the stories written, there’s a lot of cobwebby code now exposed that probably hasn’t been used in several years. For example, I’ve no idea if anyone uses the PelikhanAttribute class [http://temp.mbunit.com/html/T_MbUnit_Framework_PelikhanAttribute.htm] but I’m guessing that Peli wrote it in the dawntime of the project when it was called gUnit. What this site represents at the moment is a statement of intent and I want as many people as possible to give us some feedback on this. Are we making the right move? What further user stories do you want to see? What namespaces do you want to see documented next? MbUnit has a good size set of users out there - let’s hear from you and not disappoint. Especially as what we learn from this process will have a significant influence on how we produce documentation for Gallio and that will be mighty fine.Posted on August 13, 2007 #MbUnit Documentation