 |
Document! X 5, £299.00 (about $560) If you're a developer in a small or medium sized shop, you've probably been faced with the task of documenting your code at some point. You may have looked wistfully at the MSDN documentation for the .NET Framework and wished that you could turn out similarly-polished documentation for your own class libraries. And perhaps, armed with the XML commenting facility in C# or VB 2005 and enough time, you've tried to see what you can do along those lines. You may even have had some success with the open-source NDoc program, though its support for .NET 2.0 is shaky at the moment. If you're ready to turn to a professional (and commercial) application, Document! X offers an amazingly fast and easy way to create documentation for a wide variety of code. The basic idea here is simple: you point Document! X at your code, and it builds the skeleton of a help file for you, in what we've come to expect as the standard format (for .NET code, that's MSDN-style, though you can choose from several built-in templates or choose your own). This pre-built version contains topics for every object and member in your code, along with all the boilerplate text you'd normally type a zillion times and the hyperlinks to tie it all together. Then you use Document! X to add your own content (the detailed explanations of what each member is good for, as well as any overview and other custom material) and to create the help file. The new version does support .NET 2.0 and Visual Studio 2005, but it can also handle a bunch of other things:
One of the things that impresses me the most about Document! X (and which I've chosen to highlight in the little movie below) is the way that it handles XML comments in .NET code. When you install the product, it installs an add-in in Visual Studio .NET. Click the Edit Documentation toolbar button and it opens up a new tab in the IDE, showing a treeview of all of the members in your project. Click on a member and you'll be presented with the help page for that member, the way it will look in the final compiled help file. Then just click and type right in that page to fill in things like the summary and the definitions of inputs and return values. When you switch back to your source code, you'll find that Document! X has built all of the XML comments for you. I love any tool that protects me from angle brackets this way. Similar add-ins bring live commenting to the VB and VBA IDEs. Document! X also has its own IDE for managing help projects. Here you can choose what to document, adding as many assemblies and databases and so on to a single project as you like. You can tweak the table of contents for the generated help file, which is made up of a combination of rules ("generate nodes for all classes within each namespace") and fixed topics. You then proceed to the content editor, where you can apply additional tweaks to the automatically-generated documentation. A click of the Build button, a bit of a wait, and compiled help and Web-based HTML help fall out of the other end of the process. There are a lot of nice little touches here. The content editor lets you easily add code samples and handles converting them to HTML markup for you (indeed, you never have to look at HTML at all here, even though the templates for MSDN-style help are quite complex). You can build both HTML Help 1 (suitable for standalone) and Help 2.0 (suitable for integration with .NET help) files. The product also integrates with HelpStudio, Innovasys's more general help-file builder, if you want to include developer documentation as part of a larger help file. The navigation tools are excellent - for example, you can easily jump to the next topic that lacks documentation, making it easy to avoid shipping a help file with holes in it (something I see more often than you'd expect). I did find a few rough edges (screen repaints on my older video card occasionally got a bit wonky), but nothing that seriously impaired functionality. This is definitely on the short list of tools to evaluate if you want to build MSDN-style help for .NET projects. I'd also look at it seriously for documenting older technologies. By building the skeleton for you, with all classes, methods, properties, enums, and so on already in place and formatted, this tool can save you a tremendous amount of time. If you're billing any sort of reasonable hourly rate, it will pay for itself quickly. You can download an evaluation version here.
Mike Gunderloy is the lead developer for Larkware and author of numerous books and articles on programming topics. Published May 29, 2006 |
