anand raman, group manager david wright, lead sde developer division march 15, 2007
TRANSCRIPT
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.