Anand Raman, Group ManagerDavid Wright, Lead SDE

Developer Division

March 15, 2007

Who We areWho We areOrganizationOrganization

Developer Content and International Product Developer Content and International Product GroupGroup

ProductsProducts

Visual Studio (VS) help Visual Studio (VS) help

Windows SDK (WSDK) HelpWindows SDK (WSDK) Help

VS & WSDK localizationVS & WSDK localization

GlobalizationGlobalization

ToolsTools

Developer content and translation wikiDeveloper content and translation wiki

SandcastleSandcastle

DocStudio power packDocStudio power pack

About this presentationAbout this presentationObjectivesObjectives

OverviewOverview

ArchitectureArchitecture

Sandcastle StatusSandcastle Status

Community EngagementCommunity Engagement

Best PracticesBest Practices

SummarySummary

QuestionsQuestions

ResourcesResources

ObjectivesObjectives

After attending this presentation, After attending this presentation, you'll be able to:you'll be able to:

Understand Sandcastle architectureUnderstand Sandcastle architecture

Find out development lessons we learned from Find out development lessons we learned from SandcastleSandcastle

Get your daily build documentation via Get your daily build documentation via Sandcastle (we can help)Sandcastle (we can help)

Give us feedback on SandcastleGive us feedback on Sandcastle

6

OverviewOverviewSandcastle documents /// comments in source Sandcastle documents /// comments in source code.code.

Mission StatementMission Statement

Enabling managed class library developers Enabling managed class library developers throughout the world to easily create throughout the world to easily create accurate, informative documentation with a accurate, informative documentation with a default (common) look and feeldefault (common) look and feel..

7

Why Sandcastle?Why Sandcastle?

Mscorlib.dll - With SandcastleMscorlib.dll - With Sandcastle

8

Documentation Process using SandcastleDocumentation Process using Sandcastle

C# or VBsource files

csc /doc

assemblies

XMLfiles

Sandcastle

HTMLtopics

projectfile

TOCfile indexes

Help ViewerHTML Help

Compiler

Sandcastle LibrariesSandcastle Libraries External ToolsExternal Tools Source FilesSource Files

A Software Development StoryA Software Development Story

Problem SpaceProblem Space

Fast, flexible Fast, flexible internalinternal doc build engine doc build engine

Don’t Don’t externalexternal customers do this, too? customers do this, too?

Problems:Problems:Different XML languagesDifferent XML languages

More data sources for internal buildsMore data sources for internal builds

Simplicity more important for external usersSimplicity more important for external users

Our TeamOur Team

1 half-time Manager/PM (Anand 1 half-time Manager/PM (Anand Raman)Raman)

1 full-time SDE (David Wright)1 full-time SDE (David Wright)

1 half-time SDET (Pritam Bhat)1 half-time SDET (Pritam Bhat)

Many more contributors…Many more contributors…4+ internal teams doing testing4+ internal teams doing testing

2+ internal teams contributing code2+ internal teams contributing code

100s of 100s of activeactive external testers external testers

several several activeactive external extension external extension coderscoders

What is Sandcastle?What is Sandcastle?

BuildAssemblerBuild

Assembler

MRefBuildeMRefBuilderr

MRefBuildeMRefBuilderr

Copy Copy Transform Replace

Inside BuildAssembler

MRefBuildeMRefBuilderr

MRefBuildeMRefBuilderr

BuildAssembleBuildAssemblerr

BuildAssembleBuildAssemblerr

BuildAssembler BuildAssembler ConfigurationConfiguration<<componentscomponents>>

<<componentcomponent typetype==“Transfrom” “Transfrom” assemblyassembly==“Components.dll” “Components.dll” >>

<<transformtransform filefile==“sandcastle.xsl” “sandcastle.xsl” >>

<<argumentargument namename=“metadata”=“metadata” valuevalue==“true”“true” /> />

</</transformtransform>>

</</componentcomponent>>

<!-- <!-- add another component hereadd another component here --> -->

<<componentcomponent typetype==“Save” “Save” assemblyassembly==“Components.dll” “Components.dll” >>

<<savesave basebase==“Output\html” “Output\html” pathpath==“concat(/html/@file,’.htm’)”“concat(/html/@file,’.htm’)” /> />

</</componentcomponent>>

<<//componentscomponents>>

Component ArchitectureComponent Architecturepublic abstract classpublic abstract class BuildComponent BuildComponent {{

protectedprotected BuildComponent (XPathNavigator configuration) BuildComponent (XPathNavigator configuration) {{

// initialize component using XML configuration data// initialize component using XML configuration data

}}

public abstract voidpublic abstract void Apply (XmlDocument document, string id) Apply (XmlDocument document, string id) {{

// do the work of the component on the document// do the work of the component on the document

}}

// methods to facilitate logging// methods to facilitate logging

}}

Community EngagementCommunity Engagement

OutreachOutreachDownloadDownload

BlogBlog

ForumsForums

ResponseResponseInquiriesInquiries

SolutionsSolutions

ExtensionsExtensions

BlogBlog

Forum ActivityForum Activity

Sandcastle GUI by Sandcastle GUI by CustomerCustomer

Best practicesBest practices

Development LessonsDevelopment LessonsPick a good problem spacePick a good problem space

Good componentization facilitates developer Good componentization facilitates developer ownership and cooperationownership and cooperation

Establish and track performance metricsEstablish and track performance metrics

Release early, release often, both internally and Release early, release often, both internally and externallyexternally

Prioritize work based on feedbackPrioritize work based on feedback

Respond to feedbackRespond to feedback

21

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

Works with or without authored comments.Works with or without authored comments.

Can support all .NET languages.Can support all .NET languages.

Supports Generics and .NET Framework 2.0.Supports Generics and .NET Framework 2.0.

Supports .NET Compact Framework projects.Supports .NET Compact Framework projects.

Simple compiler interface or Visual Studio add-Simple compiler interface or Visual Studio add-in.in.

Very fast performance.Very fast performance.

Supports localization.Supports localization.

22

Presentation FeaturesPresentation FeaturesMSDN-like layout and look & feel.MSDN-like layout and look & feel.

Auto-generated index entries, TOC entries, topic Auto-generated index entries, TOC entries, topic chunking, and page layout promote consistency chunking, and page layout promote consistency and familiarity.and familiarity.

Auto-generated syntax declaration sections.Auto-generated syntax declaration sections.

Auto-generated inheritance tables.Auto-generated inheritance tables.

Code colorization.Code colorization.

Multiple styles and language selection give end Multiple styles and language selection give end user the ability to select their favorite user the ability to select their favorite preferences. preferences.

FutureFuture

V 1.0 RTW end of AprilV 1.0 RTW end of April

Documentation compilers for Documentation compilers for schema, web services and schema, web services and unmanaged codeunmanaged code

Delivered as a part of VS SDKDelivered as a part of VS SDK

Avalon based viewer for Sandcastle Avalon based viewer for Sandcastle xml outputxml output

ResourcesResources

Sandcastle Team BlogsSandcastle Team Blogshttp://blogs.msdn.com/sandcastlehttp://blogs.msdn.com/sandcastle

Sandcastle websiteSandcastle websitehttp://www.sandcastledocs.com

Sandcastle supportSandcastle supportSandchlpSandchlp

© 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.

The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions,

it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.