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.

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

comments powered by Disqus


  • AI for GitHub Collaboration? Maybe Not So Much

    No doubt GitHub Copilot has been a boon for developers, but AI might not be the best tool for collaboration, according to developers weighing in on a recent social media post from the GitHub team.

  • Visual Studio 2022 Getting VS Code 'Command Palette' Equivalent

    As any Visual Studio Code user knows, the editor's command palette is a powerful tool for getting things done quickly, without having to navigate through menus and dialogs. Now, we learn how an equivalent is coming for Microsoft's flagship Visual Studio IDE, invoked by the same familiar Ctrl+Shift+P keyboard shortcut.

  • .NET 9 Preview 3: 'I've Been Waiting 9 Years for This API!'

    Microsoft's third preview of .NET 9 sees a lot of minor tweaks and fixes with no earth-shaking new functionality, but little things can be important to individual developers.

  • Data Anomaly Detection Using a Neural Autoencoder with C#

    Dr. James McCaffrey of Microsoft Research tackles the process of examining a set of source data to find data items that are different in some way from the majority of the source items.

  • What's New for Python, Java in Visual Studio Code

    Microsoft announced March 2024 updates to its Python and Java extensions for Visual Studio Code, the open source-based, cross-platform code editor that has repeatedly been named the No. 1 tool in major development surveys.

Subscribe on YouTube