Product Reviews
Ease .NET Code Documentation Pain
If you're documenting your .NET code for other developers, you should follow the standards that Microsoft has developed. Document! X 2011 for Visual Studio will make that job considerably faster and easier.
If there are developers who enjoy documenting their code, I haven't met them. But if you're a developer who documents your code, Innovasys Document! X will substantially reduce the costs involved, provide a framework for your documentation and ensure that your documentation is delivered in a familiar format: Visual Studio Help.
After installing Document! X, you'll find a new menu bar in Visual Studio that includes an Open Document! X button (disabled in ASP.NET Web site projects). The first time you click the button, Document! X gives you a list of DLLs that it will generate document support for in your project. Document! X makes smart choices in selecting which DLLs will be documented by default -- it doesn't select system DLLs or the Visual Basic My namespace, for instance. Any subsequent time you use the button within your project, you'll open the Document! X IDE with the documentation project for your solution loaded.
By default, a quick start page is displayed when Document X! starts to let you finish configuring your documentation project. You can, for instance, add additional components to your documentation project. Document! X will generate the structure for documenting databases, XSD schemas and COM components. It will even take a stab at JavaScript libraries (though not the JavaScript in your .aspx pages).
All of the documentation components generated for your application are kept, by default, in a folder named "documentation" in your application project's folder structure. Document X! also provides integration with Subversion and other source-control tools to let you track and share those components.
[Click on image for larger view.] |
| Figure 1. Generating Developer Documentation: After specifying the DLLs you want to document, Document! X generates the Help pages for the contained classes -- but it's still your
responsibility to write the content. |
Automated Process
There's a wealth of features in Document! X. A task list, for instance, provides a rudimentary form of project management for your documentation project. While aimed at the .NET developer, Document! X will also analyze COM components you add to your documentation project and provide skeleton documents for them. Several customizable templates for generating documentation are provided, including support for Visual Studio 2008 and 2010 styles. A command-line tool for building your documentation output is included so that you can generate your documentation as part of an automated process.
Surprisingly, the Document! X help system let me down. While I was impressed with the quality overall, I couldn't figure out how to generate the object model relationship diagrams.
Some additional components may be required to generate your documentation. Before you can have a Document! X project generate a Windows Help file, you'll need to download and install the Microsoft Help Compiler (which is free). Within your Document! X project you can activate Community Features to create pages that end users can update by selecting a single option. To make that work, however, you'll either need to add Innovasys Community Extensions to your Web server or purchase a subscription to the Innovasys hosting service.
There are several assumptions here -- that you'll document your code and that you'll do it to the level that Microsoft provides for the Microsoft .NET Framework components. If you're developing software to be used within your own organization (or only by yourself), you may feel that you don't need that level of documentation.
Innovasys Ltd.
Web: innovasys.com
Phone: 617-500-7099
Price: $613 with support and upgrades, $484 without; $1,610 for a Community Extensions license
Quick Facts: Supports creating developer documentation integrated with Visual Studio
Pros: Will significantly reduce the cost and time required to document .NET projects
Cons: Generates documentation for developers, not end users
About the Author
Peter Vogel is a system architect and principal in PH&V Information Services. PH&V provides full-stack consulting from UX design through object modeling to database design. Peter tweets about his VSM columns with the hashtag #vogelarticles. His blog posts on user experience design can be found at http://blog.learningtree.com/tag/ui/.