Creating API Documentation

Some customers have asked my how we create our API docs internally and what tools they can use…  Some of you may have already heard about Sandcastle, but I thought I’d spread the word even more..

Sandcastle enables managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel. Internally we use Sandcastle to ship .NET Framework documentation and also documentation to and

Sandcastle Highlights:

· Produces quality, comprehensive, familiar MSDN-like documentation.

· Works with or without authored comments.

· Supports Generics and .NET Framework 1.x, 2.x and 3.x

· Sandcastle has 2 main components (MrefBuilder and Build Assembler)

· MrefBuilder generates reflection xml file for Build Assembler

· Build Assembler includes syntax generation, transformation..etc

· Sandcastle is used internally to build .Net Framework documentation

Sandcastle Architecture:

Please see the post at

Sandcastle wiki site

Molly recently setup a wiki site to share Information about Sandcastle to our customers: On this web site, you can find links to the following information:

Sandcastle Blogs:

Comments (7)

  1. Marcos says:

    Sorry that I cant belive it but you said

    "Internally we use Sandcastle to ship .NET Framework documentation"

    i.e. You have used SandCastle for the docs of the .NET 2.0 framework in 2005 ???

    Or even more have you used sandcastle for the .NET 1.1 docs ??

    I dont think that SandCastle was ready all that time ago, if yes, we love to see it ready now for really use, a lot of years has pased.

    You dont use any other tool than SandCastle ??

    again, I cant belive that, sorry


    Keep in good work

  2. Brad Abrams says:

    Fair point..I beleive we are using SandCastle for .NET Framework 3.5, but I am not 100% sure, I will check.

    have you used it?  what do you think?

  3. Marcos says:

    I have tried it some time ago, and I was a bit frustrated, the .NET developer community love so much NDoc that a solution that need a lot of XML edition, or call to a lot of line commands, etc is out of what we want.

    Maybe SandCastle is the best ever designed documentator but there are a lot of things to do in Usability and and in the output.

    I left you some links of others developers

    For example the online MSDN dont remember my language selections in the examples, and is imposible to belive that THERE IS NOT A "Select all" "Select None" links !!!

    We go to a method documentation, and if we are c# developers we need to uncheck all this:

    Visual Basic





    One by one !! no "Select none" a good usability idea can be that if you click in ONE language you get only the examples in that one.

    Better dont talk that when we go to other page we lost the selection =(

    The SandCastle output has the same mistakes that can make anyone to ungry 😛

    The .NET developers need to open a GUI, drop some assemblies there, and generate the docs.

    Just my 2 cents to the topic

    I hope that SandCastle become a real alternative soon, we lost the NDoc project based on the lack of community help and donations, and the lack of MS support on the other side.

    I still use NDoc for the docs of my projects and to create my site, all is based on a single ndoc file, I call a commandline from my NAnt script and walla I have my site and my chm =)

    Thanks for hear us always.

    Sorry for my english


  4. aram says:


    My name is Anand and I am a Group Manager at Microsoft. My teams builds Sandcastle. We used Sandcastle to ship the Orcas Beta 1 documentation and Framework 3.5.

    If you are interested in nDoc style GUI it’s available for Sandcastle at It’s a codeplex project written by a customer.

    Regarding the language selection we are releasing a new documentation design with the next release of Sandcastle to address this issue.

    If you are interested in additional details please email me at Cheers.


  5. Simon says:

    Here is a pretty GUI for sandcastle

  6. d says:


    Can you go into more depth on the process Microsoft uses to generate their documentation, not just specifically the tools (though more info on those would be nice), but the overall process?

    – Are your devs responsible for writing their own code comments?

    – Do your tech writers review every doc comment?  If they do, there not in the actual code are they?

    – Do you use the <include> comment tag to keeps all of the comments external?

    – If you do, how do you manage the process of creating a new comment in the external doc then pointing the code comment to it?

    – How do you manage code snippets in the API docs to ensure their quality?

    Microsoft is unique in the overall size and quality of the API docs they provide, but there are other orgs out there in somewhat similar situations that would love to learn how you guys do it.

  7. Anand Raman says:

    Please see”> for an high level overview of Microsoft internal documentation process. The latest Sandcastle stack replaces the entire "Coronado" set of tools in the diagram.

    We maintain a seperate snippet store and run a test harness for various tests such as compile. We also have tools to generate the OGF rating for APIs we document.

    I will do a detailed blog about this at