P3.NET

SandCastle – Is It Blowing Away?

I’m really, really disappointed with Microsoft about SandCastle.  For those of you not in the know SandCastle (SC) is the documentation generator from Microsoft.  Supposedly they use it internally for generating the .NET Framework documentation but with the tools they released publicly I find it hard to believe.  The last time SC was updated was 2010.  It’s been over a year and I still can’t generate anything near the style or accuracy of the existing documentation. 

I long for the days of NDoc where I could pass my documentation on to a GUI tool and it could spit out the professional looking documentation.  With SC it spits out beta quality documentation with styles that hardly work and absolutely cannot handle anything beyond basic doc comments.  This is really sad.  It doesn’t even ship with a GUI so I can configure the various options to generate something reasonably close without having to read through help files.  Fortunately there are third-party tools available but honestly they don’t update that often either.

What makes me really mad is that the whole reason SC is suppose to be so awesome is that it is configurable to the point that we should be able to generate any style of documentation.  The reality though is that the existing styles are horribly broken, can’t handle any external stuff and doesn’t even match the existing framework styles.  You’d figure that MS would release the very same style and resources that are used for the framework but I’ve yet to see any SC-generated documentation come close. There’s always something broken whether it is bad image references, poorly formatted examples or just plain ugly styles.

Don’t even get me started on the horrible new MS Help system that was introduced in VS2010.  Help is sliding so far backwards that I think MS needs to just start over.  The day we can’t ship a simple help file (or even a bootstrapper) is a sad day indeed.  I’d hate to be the folks at MS who have to go through all the steps needed to install/modify help files just for testing.  This is truly ridiculous and a bad, bad sign for help in general.

Therefore I throw out the challenge for MS to step up to the plate and actually provide us an updated version of SC that can generate MSDN-style documentation out of the box without all the extra work generally involved.  Better yet, integrate this functionality into VS directly so I don’t have to use third-party tools.  Unless MS can fix SC I feel that it’ll fall to the wayside like so many other MS projects.  This is unfortunate because documentation is key to good class library design.