LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables

by Mary Connor on Nov 04, 2011

1,161 views

Speakers: Mary Connor and Nicky Bleiel ...

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.

Less

4 Embeds 546

http://www.cleverhamster.com	527
http://paper.li	14
http://cleverhamster.typepad.com	4
http://us-w1.rockmelt.com	1

Statistics

Favorites: 0
Downloads: 18
Comments: 0
Embed Views: 546
Views on SlideShare: 615
Total Views: 1,161

LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables — Presentation Transcript

Double Trouble!Adding Developer Docs to Your Deliverables LavaCon Conference November 15, 2011 Mary Connor and Nicky Bleiel

Presenters Mary Connor  Documentation Architect, Advanced Solutions International  www.cleverhamster.com  mconnor@advsol.com Nicky Bleiel  Lead Information Developer, ComponentOne Doc-To-Help  www.nickybleiel.com  nickyb@componentone.com

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 Innovasysadded

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 servicesSuddenly, API was our core business! Presentation • HTML, web controls1. internal developers • Devices, phones create all new functionality using Services SOA • Web service, SOA2. third-party developers • Decentralization need SOA to use and Back-end extend our product, as • SQL databases well as to integrate • Content management their own products

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 SolutionDOCX-based content Code-generated content Embedded diagrams

What is Sandcastle?Sandcastle is a documentation generator fromMicrosoft that automatically produces MSDNstyle reference documentation out of reflectioninformation of .NET assemblies and XMLdocumentation comments found in the sourcecode 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 docsWhat 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 TranslationManagement 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?

LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables

by Mary Connor on Nov 04, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

4 Embeds 546

Statistics

LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables — Presentation Transcript