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 principal in PH&V Information Services, specializing in Web development with expertise in SOA, client-side development, and user interface design. Peter tweets about his VSM columns with the hashtag #vogelarticles. His most recent book ("rtfm*") is on writing effective user manuals, and his blog on language and technical writing can be found at rtfmphvis.blogspot.com.

comments powered by Disqus

Reader Comments:

Fri, Aug 26, 2011 Peter Vogel Canada

Good points! I've looked at GhostDoc earlier(http://visualstudiomagazine.com/articles/2010/04/16/vstoolbox-free-tools.aspx and http://visualstudiomagazine.com/blogs/tool-tracker/2010/04/documentation-with-ghost-doc.aspx). But, I think, without one of the Sandcastle GUI's (like Sandcastle Help File Builder which you mention) generating your CHM files is going to be labour intensive. Document! X certainly reduces the setup and integration time . What you won't get with any of these tools is the support that Document! X provides for all of the stuff that isn't in the DLL and may not be part of your XML Documentation--e.g. why this class/member/form was created and what it's design goals were.

Wed, Aug 17, 2011 Richard

Alternatively:

Use GhostDoc [1] to simplify generating XML doc-comments;

Use Sandcastle [2] and Sandcastle Help File Builder [3] to build CHM files from your comments;

Total cost: $0

[1] http://submain.com/GhostDoc/
[2] http://sandcastle.codeplex.com/
[3] http://shfb.codeplex.com/

Add Your Comments Now:

Your Name:(optional)
Your Email:(optional)
Your Location:(optional)
Comment:
Please type the letters/numbers you see above

.NET Insight

Sign up for our newsletter.

I agree to this site's Privacy Policy.