lavacon 2011: double trouble! adding developer docs to your deliverables
DESCRIPTION
Speakers: Mary Connor and Nicky Bleiel Here is how one team added new developer documentation to its already long list of end-user deliverables, with no additional headcount, tools, or resources. Our next-generation product combines web controls with web services, and the API for those web services has to be documented for both internal and third-party developers. Having just migrated our legacy user documentation to Doc-To-Help to solve Agile authoring problems, we were able to leverage its API-generation feature to automate builds of the references we needed. Doc-To-Help lets us share authorship of developer documentation in easy, familiar formats and reuse that content among user docs, context-sensitive Help files, training materials, and websites.TRANSCRIPT
LavaCon ConferenceNovember 15, 2011
Mary Connor and Nicky Bleiel
Double Trouble!Adding Developer Docs to Your Deliverables
Presenters
Mary Connor Documentation Architect,
Advanced Solutions International www.cleverhamster.com [email protected]
Nicky Bleiel Lead Information Developer,
ComponentOne Doc-To-Help www.nickybleiel.com [email protected]
What are API docs?
• application programming interface (API)
Creating a public API for your application — and documenting it — lets third-party developers
• extend what your application can do• integrate your functionality into theirs
…which means $
2000: Coder-free hand-off to writer• API to write web pages that talk to back office• Document! X by Innovasys
added
2005: Hands-free, writer-free• NDoc automated builds
No overviews
Drupal wiki for dev articles
Link to Help
Starter articles
Web 2.0 world: web controls + web services
Suddenly, API was our core business!
1. internal developers create all new functionality using SOA
2. third-party developers need SOA to use and extend our product, as well as to integrate their own products
Presentation•HTML, web controls•Devices, phones
Services•Web service, SOA•Decentralization
Back-end•SQL databases•Content management
Enter Sandcastle, for .NET and VS
• The promise of Intellisense• The pain of Microsoft XAML
Serendipity! Doc-To-Help
• We’d just migrated to Doc-To-Help, for Agile• Doc-To-Help includes a
Sandcastle plug-in• Easy authoring• Complete integration
of conceptual with API• NO NEW COSTS!
Happy dance
Our Doc-To-Help Solution
DOCX-based content
Code-generated content Embedded diagrams
What is Sandcastle?
Sandcastle is a documentation generator from Microsoft that automatically produces MSDN style reference documentation out of reflection information of .NET assemblies and XML documentation comments found in the source code of these assemblies. (Whew.)
Source: wikipedia
Doc-To-Help + SandcastleStart with the Doc-To-Help Sandcastle plug-in and add…• Assembly file (.dll)• XML comments file(s) (.xml)…to create MSDN-style reference docs
What Doc-To-Help does:• Automatically creates the Table of Contents and Index based on the structure
of the assembly.• Gives you the power to create 6 different types of outputs:
– Microsoft Help Viewer (integrates with Visual Studio 2010)– Help 2.0 (integrates with Visual Studio 2007 and 2005)– HTML Help– NetHelp (browser-based Help)– WinHelp– JavaHelp
• Makes it possible (& easy) to link “Narrative” content to the reference docs.
Sandcastle Ribbon
Demo
Other Integrations
• Team Foundation Server• SharePoint
Translation ManagementDon’t miss Brad’s talk 3 pm today Automating Translation Management and Locale-specific Builds
What’s next?
• Move API documentation project to Dev’s build machines
• Integrate D2H project fully into TFS• Rebuild API documentation when code
checked in • Sourcing conceptual diagrams in cloud tool• Localization requirements and options
Questions?