# Wednesday, May 23, 2007

I finally got around to building some docs for our latest project, and decided to go with Sandcastle rather than NDoc for the time being.  I got the March CTP of Sandcastle and started trying to figure out how to get it working with our build. 

While the resulting CHM file came out looking really nice, I'd have to say that Sandcastle is WAY not ready for prime time.  There is little to no documentation, so figuring out how to customize things is largely an exercise for the user.  I was willing to exercise, but many aren't. :-)  The build itself is very complicated, with 10-12 separate steps required to produce the CHM file, and lots of rough edges, like the fact that the MRefBuilder tool won't look for dependencies in the GAC, so I had to copy a bunch of core BCL assemblies out of the GAC and into my build directory to get the docs to build.  Lame. 

As it stands now, Sandcastle is useful only to serious build weenies, since it's too cumbersome for the average developer to deal with.  This is too bad, since it's being touted (at least in some circles) as the "right" solution for building docs going forward.  It smacks of something that the VS 2005 team built to create there docs, then decided to make public.  It's not quite there yet.

Friday, May 25, 2007 8:04:24 AM (Pacific Daylight Time, UTC-07:00)
Are you guys just trying to create a CHM file? I played with Sandcastle a little bit and was able to get VS integrated help from it. I had to have the VS 2005 SDK on the "build box", though. I agree, though, it's a "nic" but still has room for growth.
Friday, May 25, 2007 10:08:59 AM (Pacific Daylight Time, UTC-07:00)
I had the same experience. It's clearly the right thing, so I'm not going to start any major doc building initiatives that don't use it -- but I'm holding off for now. Hopefully the next CTP will be better.
Jeff Paulsen
Friday, May 25, 2007 12:26:25 PM (Pacific Daylight Time, UTC-07:00)
There are also some tools that look like they make it easier up on CodePlex. There's a visual studio integration project that works pretty smoothly, and makes the Sandcastle docs a separate project of your VS solution. If basically builds docs for everything it finds as a project reference of the doc project.
Comments are closed.