LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables
•Descargar como PPTX, PDF•
1 recomendación•2,416 vistas
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.
Recomendados
Recomendados
Más contenido relacionado
La actualidad más candente
La actualidad más candente (20)
Similar a LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables
Similar a LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables (20)
Último
Último (20)
LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables
- 1. Double Trouble! Adding Developer Docs to Your Deliverables LavaCon Conference November 15, 2011 Mary Connor and Nicky Bleiel
- 2. 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
- 3. 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 $
- 4. 2000: Coder-free hand-off to writer • API to write web pages that talk to back office • Document! X by Innovasys added
- 5. 2005: Hands-free, writer-free • NDoc automated builds No overviews
- 6. Drupal wiki for dev articles Link to Help Starter articles
- 7. Web 2.0 world: web controls + web services Suddenly, API was our core business! Presentation • HTML, web controls 1. internal developers • Devices, phones create all new functionality using Services SOA • Web service, SOA 2. 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
- 8. Enter Sandcastle, for .NET and VS • The promise of Intellisense • The pain of Microsoft XAML
- 9. 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
- 10. Our Doc-To-Help Solution DOCX-based content Code-generated content Embedded diagrams
- 11. 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
- 12. Doc-To-Help + Sandcastle Start 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.
- 14. Demo
- 15. Other Integrations • Team Foundation Server • SharePoint
- 16. Translation Management Don’t miss Brad’s talk 3 pm today Automating Translation Management and Locale-specific Builds
- 17. 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
- 18. Questions?
Notas del editor
- 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.
- 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:Throughout the year, I gathered emails about changes and enhancements that needed to go into the API documentation.Right before release, the developers sent me the latest DLLs.In Document! X, I pointed the project to the new DLLs.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).I compiled the project, checked it, and gave the CHM back to Dev for production.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.
- 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. Build engineers set up NDoc to auto-build MSDN-style online Help from our C# libraries, so that it refreshed on a regular basis.They copied the generated files out to the webserver that hosted our new developer wiki. For security, they linked to the NDoc-built Help only from members-only wiki pages: 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.I added summaries of API enhancements to the formal release notes.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.
- 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 SOAthird-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.
- 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):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.
- 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.
- How it worksIn 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.At build time, a command-line batch file copies the DLLs from the network location where our continuous integration builds publish them.Another batch file performs a “get” command from TFS source control, to get the very latest DOCX conceptual content.The batch file then builds the API Help target, which merges in the conceptual documentation.Doc-To-Help invokes the Sandcastle compiler, which extracts the code comments (XML) and constructs the API reference based on the code itself (DLLs).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.
- Released in: July 2006, a few days before NDoc was declared dead Initially had no interface. Now has a lightweight one.Is available on CodePlex; ComponentOne has contributed to the code base. We contributed code that improved support for the new Microsoft Help Viewer output.
- “Narrative” is conceptual, quick starts -- “everything else”, authored in Word, XHTML Editor, HTML
- D2H has a TFS integration -- you can upload your entire project to TFS and take advantage of the features of Team Foundation Server.SharePoint integration allows you to:Share docs/graphics in your project to a SP document library (synchronous)Share docs to a SharePoint translation library and kick off a translation workflow (we will talk about this in a minute)Publish NetHelp output to SharePointPublish output to a SharePoint wiki
- We’re far from done with our API documentation:Move API documentation project to one of the automated build machines that compile our softwareIntegrate the Doc-To-Help project fully in TFSHave rebuilds of the API documentation triggered my relevant code check-insDevelop strategy for sourcing conceptual diagrams in collaborative toolExplore localization requirements and options