LavaCon 2011 Austin, TX

November, 15, 2011

Double Trouble!Adding Developer DocsAdding Developer Docs

to Your Deliverablesto Your Deliverables

Mary Connor and Nicky Bleiel

Presenters...................................................2

Summary.....................................................2

What are API docs?....................................2

2000: Coder-free hand-off to writer.............2

2005: Hands-free, writer-free.......................2

2010: web controls + web services..............3

Enter Sandcastle, and its limitations............4

Serendipity: Doc-To-Help’s Sandcastle Plug-In. 5

What is Sandcastle?....................................6

Doc-To-Help + Sandcastle..........................7

Linking Narrative to Reference with the Sandcastle Ribbon 7

Demonstration of the Doc-To-Help Sandcastle Plug-in 8

Other Integrations: TFS and SharePoint.....8

Managing Translations................................8

Next Steps...................................................9

PresentersMary Connor (www.cleverhamster.com), a past president of STC Austin, has an M.A. in English and has been teaching and performing technical communication for over 20 years. Currently the Documentation Architect for Advanced Solutions International, she specializes in software documentation and training materials, single-sourcing and content management, usability and universal design, and information system design. She manages wiki content, is researching how to develop content and deliver training using social technologies, and is cross-training in programming and automated testing within her Agile scrum team.

Email mconnor@advsol.comTwitter @maryfconnor

Nicky Bleiel (www.nickybleiel.com) is the Lead Information Developer for Doc-To-Help. She has 16 years of experience in technical communication; writing and designing information for software products in the documentation, media, industrial automation, simulation, and pharmaceutical industries. She is a Director-At-Large of the Society for Technical Communication and has presented talks at WritersUA, STC, tcworld, LavaCon, and CIDM on many topics, including embedded help, tools and technologies, user assistance design, single sourcing, wikis, Web 2.0, and convergence technical communication.

Email nickyb@componentone.com Twitter @nickybleiel

SummaryHere 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.

What are API docs?An application programming interface (API) is a set of rules (coded handshakes) that software programs can follow to work together. An API serves to link up different software programs and enable them to interact, rather as a user interface lets humans interact with computers (I click on a specified region of the display with my input device to signal the computer to run a command for me – and I don’t need any understanding of how that command executes under the hood to invoke it). Often API usage is about taking advantage of (making API calls to) functionality that someone else wrote, to avoid recreating the wheel yourself.Creating a public API for your application — and documenting it — makes it possible for third-party developers to

extend what your application can do, or integrate it with their own

– both of which can help to sell more of your product. It is this commercial reality that can cause you to have no API documentation responsibilities one day and find out that you have them the next.Your public API defines your "vocabularies" and conventions for asking for resources (calling functions). Your API documentation may include specifications for routines, data structures, object classes, and protocols used to communicate between the consumer program (their application) and the provider program of the API (your application).API documentation is what makes it possible for others to succeed in using your API.

2000: Coder-free hand-off to writerCreating API references is not a new thing in our shop: 10 years ago, we had a COM interface to supplement our all too limited web product, so that our resellers could write custom web pages that would work with our flagship back-office product. This COM interface was a small, side feature, not the core of our product. We didn’t charge money for it, so not much money went into its documentation.Come release time, the Visual Basic programmers compiled their API libraries (DLLs), delivered them to the build engineer, and called it done.So, roughly once a year, releasing this API required me to build a reference, an API help file. We needed to provide high-level introductions and guidance, but we had no access to the code base. We used a tool, still available today, called Document! X (by Innovasys). It allowed writers like me to add such information without writing code comments or even accessing the source code at all. The process was manual but manageable:1 Throughout the year, I gathered emails about changes and enhancements that needed

to go into the API documentation.2 Right before release, the developers sent me the latest DLLs.3 In Document! X, I pointed the project to the new DLLs.4 I updated the overview and comment files on my own system.

For example, if the Security library (asi_security.dll) got a new method called AssignProxy(), I would edit my external comment file for Security and explain why and how to use the new Proxy feature (which the developer explained to me in an email).5 I compiled the project, checked it, and gave the CHM back to Dev for production.6 I forgot about it for another year.In truth, this method produced a very minimal offering and very minimal cost. The API help had no code comments, and the technical writer only added overviews and pointed out new features. Noticeably absent from this delivery were the documentation artifacts of highest value: code samples. Code samples were created by consultants and used in training materials, and these materials could only be obtained by attending the company’s full-fee courses.

2005: Hands-free, writer-freeOur next API product moved to the C# language, using .NET; however, it existed mostly to replace the COM interface as we dropped our Visual Basic code base. To keep the API documentation project as lean and cheap as possible, the developers implemented the open-source documentation generator for .NET called NDoc. 1 Build engineers set up NDoc to auto-build MSDN-style online Help from our C#

libraries, so that it refreshed on a regular basis.2 They copied the generated files out to the webserver that hosted our new developer

wiki.

3 For security, they linked to the NDoc-built Help only from members-only wiki pages:

4 When it was time to release, I made a quick pass of collecting, organizing, and editing developer-written wiki articles to serve as the essential overview.

5 I added summaries of API enhancements to the formal release notes.6 I forgot about it for another year.Therefore, at no point did the writers handle or have responsibility for the API help posted in this way. Mostly, the technical writers participated only peripherally, and code comments were added by the programmers only incidentally. The result was an API reference that was incomplete but acceptable, given the secondary emphasis of this product.This method produced a very minimal offering at almost no effective cost: the API generator was free, as was our wiki platform (Drupal). Again, noticeably absent from this delivery were the bulk of the beefy code samples. Code samples created by consultants were kept in training materials, and these materials could still only be obtained by attending the full-fee courses.

2010: web controls + web servicesThen, Web 2.0 hit, and everything changed.Our technology sea change was a fundamental shift away from client/server technology, away from having software that installed on each desktop. Our market wanted cloud access, dynamic updates, even the ability to run our software from their smart phones.To deliver this type of modern product, the new technology stack that we needed was a combination of flexible web controls and omnipresent web services. Overnight, it seemed, we switched exclusively to creating .NET web controls that ran on top of a Service Oriented Architecture (SOA) service, which wrapped our legacy business logic in a web-friendly yet secure access layer.

This SOA service was an application programming interface much like the others we had done. However, SOA was no longer a giveaway to our resellers; now, an API was the foundation of our flagship product, and this API had to be documented, for two audiences: internal developers, who had to create all new functionality using SOA third-party developers, who had to master SOA to use and extend our product, as well as to

integrate their own productsNow API documentation was not an “add-on” to a side product, but our core offering. How we approached this had to change if we were all to succeed.

Enter Sandcastle, and its limitationsAt the same time, we realized that our API toolset had to change: Microsoft released Sandcastle as a Community Technology Preview (CTP) version in July 2006, a few days before NDoc was declared dead by its author. In addition, we were on such an old version of Drupal that we could not get the modules and updates we needed.So, our CTO approached me to figure out how to work with Sandcastle, the emerging standard for .NET-based API documentation. He showed me how Sandcastle could build native Visual Studio compiled Help, which could merge into that Help system and offer Intellisense (pop-up suggestions for code based on context):

Wonderful! This is the kind of user support that we all dream of supplying.The downside was how hard it was to add conceptual (sometimes called narrative) content into the API Help that Sandcastle builds: it uses Microsoft's markup language called XAML, and authoring content in it was far from easy. At the time, no XAML editors were available for allowing the technical writers and business analysts to write overviews, add tables and diagrams, or task out the guidance that would be critical to user success. Sandcastle could build nifty outputs, but authoring content in it was going to be miserable.

Serendipity: Doc-To-Help’s Sandcastle Plug-InDoc-To-Help (which we had just migrated to for our agile documentation needs!) happened to include a Sandcastle plug-in. This plug-in let us do deep and detailed conceptual documentation in DOCX and XHTML that merges into the generated API content from Sandcastle. The big change from our past is that Doc-To-Help lets us share authorship of developer documentation across the entire production team: business analysts, testers, developers, writers – everyone who has access to Team Foundation System in Visual Studio can update the conceptual docs in easy, familiar formats (Microsoft Word, Notepad++, etc.).Moreover, because the conceptual developer docs are in our Doc-To-Help projects, we can reuse that content among user docs, context-sensitive Help files, training materials, and websites.In sum: with no additional headcount, tools, or resources, we were able to leverage its API-generation feature to automate builds of the references we needed.

How it works1 In Doc-To-Help, I created a Sandcastle plug-in that pointed to all of the assemblies

(DLLs and XML files), and I tagged it for inclusion in a specific build target.2 At build time, a command-line batch file copies the DLLs from the network location

where our continuous integration builds publish them.3 Another batch file performs a “get” command from TFS source control, to get the very

latest DOCX conceptual content.4 The batch file then builds the API Help target, which merges in the conceptual

documentation.5 Doc-To-Help invokes the Sandcastle compiler, which extracts the code comments (XML)

and constructs the API reference based on the code itself (DLLs).6 Doc-To-Help builds a complete Help system that links the conceptual content to the API

reference, so that object names link to the topics that explain them.

What is Sandcastle?

Microsoft released Sandcastle as a Community Technology Preview (CTP) version in July 2006.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. (Source: Wikipedia)The latest Sandcastle release (June 2010) is available on CodePlex at http://sandcastle.codeplex.com/releases/view/47665. ComponentOne contributed code that improved support for the new Microsoft Help Viewer output to the Sandcastle code base.

Doc-To-Help + Sandcastle Start with the Doc-To-Help Sandcastle plug-in and add the following to create MSDN-style reference docs:

• Assembly file (.dll)• XML comments file(s) (.xml)

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. (“Narrative” includes concepts, tasks, quick starts, and other content authored in Word, Doc-To-Help’s XHTML Editor, or HTML.)

For a demonstration, check out the recorded webcast Creating API/SDK Documentation in a Click with Doc-To-Help http://vimeo.com/15367002Or see the blog post 5 Ways Doc-To-Help Makes Creating API/SDK Documentation Simple http://our.componentone.com/2010/12/27/5-ways-doc-to-help-makes-creating-apisdk-documentation-simple/

Linking Narrative to Reference with the Sandcastle Ribbon Narrative content may be linked to the automatically generated reference documentation using the Sandcastle ribbon included with Doc-To-Help.Select the text in your source document (Word, HTML, or XHTML) and click the appropriate button in the Sandcastle ribbon to create a link from narrative to the reference documentation. No mapping required.

Demonstration of the Doc-To-Help Sandcastle Plug-in

See the recorded webcast Creating API/SDK Documentation in a Click with Doc-To-Help http://vimeo.com/15367002

Other Integrations: TFS and SharePointDoc-To-Help includes an integration with Team Foundation Server; you can upload your entire project to TFS and take advantage of the features of Team Foundation Server.

Doc-To-Help’s SharePoint integration allows you to: Share the documents/graphics in your project to a SharePoint Document Library (file

synchronization is maintained). SharePoint features such as workflows and permissions can be utilized.

Share docs to a SharePoint Translation Library and kick off a translation workflow.

Publish NetHelp (browser-based) output to SharePoint. Publish NetHelp output to a SharePoint wiki.

Managing TranslationsDoc-To-Help’s integration with SharePoint allows you to upload your project to a SharePoint Translation Management Library. SharePoint Translation Management will automatically create copies of each document for every language you specify, assign translation tasks to translators, and track the workflow. Documents are automatically synchronized with the appropriate project, and after translation is complete, you can generate output.This feature will be discussed in detail at Brad Keller’s LavaCon talk: Automating Translation Management and Locale-specific Builds

For more on Doc-To-Help localization, view this recorded webcast: Easy Localization with Doc-To-Help and Microsoft SharePoint, http://vimeo.com/17921998, as well as the blog post Managing Translation with Microsoft SharePoint and Doc-To-Help: http://our.componentone.com/2010/12/22/managing-translation-with-microsoft-sharepoint-and-doc-to-help/ To learn more about Doc-To-Help, and download a free trial copy, go to: http://www.doctohelp.com/

Next StepsWe’re far from done with our API documentation: Move API documentation project to one of the automate build machines that compile

our software Integrate the Doc-To-Help project fully in TFS Have rebuilds of the API documentation triggered my relevant code check-ins Develop strategy for sourcing conceptual diagrams in collaborative tool Explore localization requirements and options