Docstoc

Double Trouble_

Document Sample
Double Trouble_ Powered By Docstoc
					                                                                         LavaCon 2011
                                                                             Austin, TX
                                                                     November 15, 2011


                       Double Trouble!
                              Adding Developer Docs to
                                      Your Deliverables

                                                         Mary Connor and Nicky Bleiel


                                                                   What is Sandcastle? .................................... 6
Presenters ................................................... 2
                                                                   Doc-To-Help + Sandcastle .......................... 7
Summary ..................................................... 2
                                                                   Linking Narrative to Reference with
What are API docs? .................................... 2              the Sandcastle Ribbon .......................... 7
2000: Coder-free hand-off to writer ............. 2                Demonstration of the Doc-To-Help
2005: Hands-free, writer-free ...................... 3                Sandcastle Plug-in ................................ 8
2010: web controls + web services ............. 4                  Other Integrations: TFS and
                                                                      SharePoint ............................................. 8
Enter Sandcastle, and its limitations ........... 4
                                                                   Managing Translations ................................ 8
Serendipity: Doc-To-Help’s
   Sandcastle Plug-In ............................... 5            Next Steps ................................................... 9
Presenters
                                  Mary 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.com
                             Twitter @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



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


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.




  Double Trouble! .................................................................................................................................................................... 2
                             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 writer
                             Creating 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.




  Double Trouble! .................................................................................................................................................................... 2
2005: Hands-free, writer-free
                             Our 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.


  Double Trouble! .................................................................................................................................................................... 3
2010: web controls + web services
                             Then, 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 products
                             Now 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 limitations
                             At 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):




  Double Trouble! .................................................................................................................................................................... 4
                             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-In
                             Doc-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.




  Double Trouble! .....................................................................................................................................................................5
                             How it works
                             1      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)


  Double Trouble! .................................................................................................................................................................... 6
                             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/15367002
                                  Or 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.




  Double Trouble! .....................................................................................................................................................................7
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 SharePoint
                             Doc-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 Translations
                             Doc-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



  Double Trouble! .................................................................................................................................................................... 8
                             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 Steps
                             We’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




  Double Trouble! .................................................................................................................................................................... 9

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:0
posted:12/3/2011
language:English
pages:10