Sandcastle - still the right thing to use? Or are there alternatives?

Question

I'm just wondering - the last release of Sandcastle is from May 2008, and it's still listed as Pre-Release Software/CTP and it's not even licensed anymore, as the EULA specifially says:

2.TERM. The term of this agreement is until September 1, 2007, or commercial release of the software, whichever is first.

As Sandcastle is rather "heavy" anyway, I just wonder if it is still the right thing to use, or if there are alternatives to create XmlDoc Documentation? (Alternatives = something I can run from my build to generate at least HTML, preferably PDF as well).

Answer 1

As far as I'm aware, Sandcastle is still a valid choice. I've used it many times in the recent past and have no issues. You can check out this page on MSDN and scroll down to the 'Documentation' section for other good choices:

C# Programming Tools

Answer 2

Microsoft Sandcastle is definitely still the right way to go. The main alternative (that offers anything close to the feature set of Sandcastle) is NDoc, but the last release of that is much older, being in January 2005!

Although it is still technically in (late) pre-release stage, it is in fact quite a stable tool. The small number of bugs have been fixed by patches, available on CodePlex as part of the Sandcastle Styles project. There's also a superb GUI for it, namely Sandcastle Help File Builder.

I am not sure about the future development of Sandcastle however. I believe it is likely Microsoft will continue work/expansion on it at some point, though there doesn't seem to be any news of when. It is certainly the only decent tool for creating proper documentation for a .NET library or application, at the moment. Of course you can often get away using more "light-weight" tools for small projects/help files. The main alternatives that I've noticed are both commercial and inferior to Sandcastle.

Generating documentation by hand/using custom automation is probably feasible in certain cases, but only for small projects (that are not likely to expand.)

Answer 3

Sandcastle is still a right choice. I used it for many projects in past.

Anyway take at look at these:

• NDoc
• GhostDoc - a free Visual Studio Extension

Answer 4

Nobody mentioned Docu, a recent project initiated by James Gregory, dev lead on FluentNHibernate.

• Announcement
• The Docu website

It's a very simple and easy to use tool that generates html documentation a la rdoc. You can easily modify templates since Docu uses Spark as the view engine.

Here is the FluentNHibernate documentation built with Docu.

Answer 5

DocProject is worth taking a look at. It takes away a lot of the pain of working with sandcastle.

Answer 6

I put a short list of some documentation tools in this SO question: anyone-using-ndoc-or-a-similar-tool

I think SandCastle is the best opensource tool currently (for documenting .NET projects), but there are several commercial tools, and they can propose better performance and more features, so if you have a budget for one of them, it worth at least evaluating what value it could bring to you.

Answer 7

To effectively use Sandcastle you need, as Noldorin pointed out earlier, to also use Sandcastle Styles and Sandcastle Help File Builder (SHFB). They all had a new release in mid-2010 so are definitely current tools.

Even with the clean and simple GUI provided by SHFB, however, there are quite a number of issues that you may need or want to consider in order to produce a tidy, professional documentation set. My article ("Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code") documenting my experience with a variety of potential pitfalls, published on Simple-Talk.com in September 2010, may save you some time, effort, and agony :-).

Another helpful resource: In October 2010 I followed up the article with a one-page wall chart that summarizes the XML documentation comment lexicon for SHFB.