Scott Hanselman

Moments ago (my time) the Sandcastle CTP was released. Here's the Sandcastle Blog and here's a PowerPoint presentation on the new project. This is a very early CTP from Microsoft that supports generating documentation from any .NET language, much like NDoc.

It's great that Microsoft is paying attention to the whole "need for help files thing." However, be warned, this is uber-early stuff, and not very smooth. Actually, it's pretty darned rough. The instructions on what your batch/build/msbuild/powershell/whatever is going to need to orchestrate is here. The instructions are ghetto. Here's a slightly less ghetto Powershell script that will at least compile the example, assuming you have Powershell.

• Assuming you have .NET 2.0 SDK and Powershell...you'll need to, of course, enable scripts via something like set-executionpolicy unrestricted
• Note: Powershell has nothing to do with Sandcastle. I just did the script because it's wicked easy in PSH.
• Download Sandcastle July CTP.
• Run this Powershell script of mine to build the example: File Attachment: sandcastledoc.ps1 (1 KB)

Remember you'll need HTML Help Workshop if you're going to make CHMs (Compiled Help files). Here's the compiled example test.chm: File Attachment: Test.chm (31 KB)

Sandcastle for .NET 1.1

One note, I was able to get Sandcastle to generate help for a .NET 1.1 application, which is a very important developer scenario I hope they don't forget about. However, Sandcastle linked the 1.1 help up to the Framework 2.0 XML help for the .NET Framework BCL (Base Class Library) by default. If you change the sandcastle.config to refer to
<data files="%SystemRoot%\Microsoft.NET\Framework\v1.1.4322\*.xml" /> (line 48 in this CTP)
it appears to link up nicely for 1.1 apps even though Sandcastle uses .NET 2.0 for its reflection.

NDoc: The Death of a (great) Open Source Project

On a related note, it's going to take a while (6 months to a year?) for Microsoft to really get Sandcastle to the point where Kevin Downs got NDoc. Will this new tool be as rich and useful? Or will it be forgotten like HTML Help Workshop?

Recently Kevin Downs, the leader of NDoc, emailed a NDoc folks announcing that NDoc is dead. I was shocked to get this email, but sadly, not surprised. Here's an important part of his email:

Unfortunately, despite the almost ubiquitous use of NDoc, there has been no support for the project from the .Net developer community either financially or by development contributions. Since 1.3 was released, there have been the grand total of eleven donations to the project. In fact, were it not for Oleg Tkachenko’s kind donation of a MS MVP MSDN subscription, I would not even have a copy of VS2005 to work with!

To put this into perspective, if only roughly 1-in-10 of the those who downloaded NDoc had donated the minimum allowable amount of $5 then I could have worked on NDoc 2.0 full-time and it could have been released months ago! Now, I am not suggesting that this should have occurred, or that anyone owes me anything for the work I have done, rather I am trying to demonstrate that if the community values open-source projects then it should do *something* to support them. MS has for years acknowledged community contributions via the MVP program but there is absolutely no support for community projects.

Apparently Kevin started getting threats - yes, you heard right, threats - about a .NET 2.0 version and has been email-bombed. He's rightfully decided to bow out after a successful run.

If you're a fan of the whole N* stack, you've used NAnt, NUnit, NDoc, NCover, for years. We take for granted that these programs just work. They are fundamental. Some folks think they are our right to possess, but they forget about the real people with real lives that write this Open Source stuff in their spare time.

Hanselman Editorial Aside: It's a shame that Microsoft can't put together an organization like INETA (who already gives small stipends to folks to speak at User Groups) and gave away grants/stipends to the 20 or so .NET Open Source Projects that TRULY make a difference in measurable ways. The whole thing could be managed out of the existing INETA organization and wouldn't cost more than a few hundred grand - the price of maybe 3-4 Microsoft Engineers.

Phil makes a good point when it compares Open Source to "Source Available" with regards to Community Server. It's great that some OS products can turn into commercial apps with an OS "lite" version.

For "base of the pyramid" fundamental stuff like Build, Test, Coverage, Docs, will we pay for them? We should. Should we have given the NDoc project $5? Did NDoc help me personally and my company? Totally. Did I donate? No, and that was a mistake. I agree with Phil. Support those 5, 10, 20 truly Open Source projects with a little of your time or money.

Personally, as an Open Source project co-leader, I'd much rather folks who use DasBlog pick a bug and send me a patch (unified diff format) than give money.  I suspect that Kevin would have been happy with a dozen engineers taking on tasks and taking on bugs in their spare time.

We are blessed. This Open Source stuff is free. But it's free like a puppy. It takes years of care and feeding. You don't get to criticise a free puppy that you bring in to your home.

Goodbye Kevin and thanks for your hard work on NDoc.

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

About   Newsletter

Hosting By