Scott Hanselman

Sandcastle - Microsoft CTP of a Help CHM file generator on the tails of the death of NDoc

July 30, '06 Comments [12] Posted in PowerShell | DasBlog | Subversion | NUnit | NCover | Nant | XML | Bugs | Tools
Sponsored By

Sandcastle1Moments 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.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by ORCS Web
Sunday, July 30, 2006 5:44:03 AM UTC
Thanks Scott for the comments and the poweshell script. We will definately post detailed instructions and architectural overview about Sandcastle in a week or so. Looking forward to hearing more feedback from you.

Anand..
Anand Raman
Sunday, July 30, 2006 3:09:48 PM UTC
It's sad to see good projects die, especially when programmer support is a main reason.

But on the other side, it's not that easy to join these projects. How many of them advertise? How often do we see "Developers wanted on [your favourite project]"?

I think these projects must advertise what they need. Do they need C++ expertise? Java? C#? UI design? How do we know what to do? Where are the tasks listed? How do we assign to them?

But our working environments are also to blame: Some employers will not let their developers spend any working hours on open source, while others may not know open source is in use, or that they should give something in return.
Thomas Eyde
Sunday, July 30, 2006 5:00:38 PM UTC
Hi Scott,

I am sad to see the end of the NDoc project.

But I don't understand the donation model. Who is supposed to donate the $5? Say I am an employee working for my company, and I am using NDoc. Should I donate the $5 personally? Or should I ask my company to pay the 5$? From my experience, getting a company to pay something can be (very) difficult, and since it is not required to pay the 5$ to use NDoc, I may not want to do a lot of work to get my company to pay the 5$. On the other hand, I may not want to spend the 5$ myself, since I am using NDoc for the company.
(Of course I am a freelancer, and not an employee, so it may be even more complicated.)

I think this may be a reason why very few people donate for a software like NDoc. Do other projects have similar problems with donations? Maybe it is not a good model? What do you think?

Sunday, July 30, 2006 5:43:58 PM UTC
To me, this is clearly a case of "bystander apathy" (http://en.wikipedia.org/wiki/Bystander_effect).

But part of it also might be the unglamorous nature of documentation to begin with :P It't not quite as sexy as say object-relational mapping and to be honest, I've come across very few developers who actually are even aware of NDoc (let's not mention even fewer who actually know how to properly document code).

With regards to this point:

=========================================
"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."
=========================================

I would think that one of the major issues holding Microsoft back from doing so is the legal bookwork that it would involve to lay the groundwork for such cooperation. As we've seen with the SCO-IBM litigation, there's a lot of gray areas to cover with regards to who owns open source code and who owns contributions to an open source project.

In the long run, however, I think it's to Microsoft's advantage to promote such projects and to ultimately foster development of a large open source toolset. You're absolutely right that Microsoft should seriously consider such a program as it ultimately brings credibility to Microsoft's products as a prosperous open source community for a given platform requires a certain maturity in the platform to begin with. I think it would go a long way in swaying many more Java developers over to .Net, which in turn sells licenses to Windows 2003, VS, and what not. Perhaps Microsoft is taking the short view on this.

=========================================
"I think this may be a reason why very few people donate for a software like NDoc. Do other projects have similar problems with donations? Maybe it is not a good model? What do you think?"
=========================================

It's a *TERRIBLE* model. Terrible. It's rare that it's well managed enough so that users and potential contributors can actually _see_ what the current contribution levels are and what is needed. For example, if it were the case that for a project "X", the developers listed the current needs (VS licenses, software package y, new servers, additional bandwidth, etc.) and such needs were itemized and placed on a website where by people could contribute either to the cost of the item or contribute the item directly, it would be much more "donater friendly".

I don't like the idea of donating money to a project if I don't know what the money is going to be used for. Is it so that the project members can get new iPods? Or is it because they need more bandwidth? A blanket "Donate Now!" link is ambiguous like that.

=========================================
But on the other side, it's not that easy to join these projects. How many of them advertise? How often do we see "Developers wanted on [your favourite project]"?
=========================================

Yup, that's a big hurdle as well. To begin with, the codebase for such projects are often *huge* (for example, the Subtext project's codebase is much larger than I would have figured for a blogging engine (but then again, maybe it's a bit too overworked for it's own good)). Aside from the daunting prospects of poring over code without a well written developer's guide (and by the way, I actually think Subtext is very good on this front), many projects don't do a very good job of explaining the contribution methodology and process (which Subtext does well, too).

No doubt that this is a wakeup call as I feel that NDoc, while probably used by only a very small % of the .Net development community (I never cease to be amazed by what passes as a "senior .Net developer") was one of the cornerstone tools that every respectable .Net developer was at least aware of if not already a part of said developer's tool chesta.
Sunday, July 30, 2006 6:04:19 PM UTC
Thomas, great point. It is important for OS developers to be more savvy about recruitment: http://haacked.com/archive/2006/07/30/OpenSourceRecruitingIsFundamental.aspx

Martin, I think it depends on a lot of factors. Are you required to use NDoc or does the use of it make your life easier at work?

In any case, monetary donations are never required. If you don't feel the need to contribute, and your company doesn't feel the need, so be it. Besides, monetary contributions are the lowest on the totem pole.

I'm not trying to guilttrip people into contributing, but merely raise awareness that contributions are needed and helpful.
Sunday, July 30, 2006 7:12:10 PM UTC
why can't INETA be that grant organization? they already get funding from Microsoft and they would elevate themselves further as an organization that fosters community project growth.
Sunday, July 30, 2006 8:35:59 PM UTC
I think this is a problem is with the Microsoft Development community in general when it comes to supporting open source projects. It may be that most in our community are not 100% aware of how Open Source really works. I'm guilty of this myself.

I've donated to several OSX projects but I've never donated to a Microsoft related project. Not sure why. Maybe because the OSX community is so small compared to the user base of Microsoft Developers.

It has to be the Microsoft Community in general. I read a blog a year ago and it said that the book publishers actually sell more OSX related books then they do on .net development! OSX has only a 4% market share, yet these books outsell .net books! Makes no sense if you look at the number of potential buyers.

Sunday, July 30, 2006 9:47:00 PM UTC
>I read a blog a year ago and it said that the book publishers
>actually sell more OSX related books then they do on .net development!

Did you see Tim O'Reilly's recent analysis? See his blog entry at

http://radar.oreilly.com/archives/2006/07/state_of_the_computer_book_mar_4.html

I think it is clear that there are many more books sold on .NET than on OSX?
Friday, August 04, 2006 1:28:44 PM UTC
Visual Studio 2005 Sandcastle Add-In

For the ones having troubles with the scripts, here a super easy add-in, with source code.

Having troubles getting it started?, let me know!

Video:
http://www.overnight.nl/download/sandcastleaddin.html

Post with rest of the links:
http://dotnetpret.blogspot.com/2006/08/sandcastle-continued-documentation.html

Cheers,

Frank Kroondijk
Saturday, August 05, 2006 3:36:53 PM UTC
I don't understand why everyone is saying NDoc is dead... it's not! The guy just decided he wasn't going to support the project and offered to hand it over to anyone who's willing to take it. So... someone steps up to the plate and it's not dead!
Sunday, August 06, 2006 5:56:10 AM UTC
I took Mikael Söderström's GenerateCHM.bat file (http://www.dotnetjunkies.com/WebLog/mikaels/archive/2006/07/30/142960.aspx)

and make it into an MSBuild target.

http://weblogs.asp.net/miked/archive/2006/08/06/Sandcastle-MSBuild-target.aspx
Saturday, September 16, 2006 2:51:50 PM UTC
Scott, I am having a blog conversation with Jason Matusow on the subject of Microsoft's support for open source projects. I thought you would enjoy jumping in. Check out this link.
Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.