Creating Developer Help Files

 < Day Day Up > 



Of course, not all documentation is intended for end users of desktop applications—some is meant for other developers. I’m not thinking here of internal documentation for your own team (I’ll discuss that briefly later in the chapter), but about documenting products that are aimed strictly at developers. The most obvious place this comes into play is when you’re delivering (and documenting) a class library. Ideally, your class library documentation should follow the format and conventions that the .NET Framework SDK established for .NET namespaces.

start sidebar
Help in the User Interface

Although I’m concentrating on help files in this chapter, you should not neglect the application’s user interface as a source of subtle but useful clues to its proper use. A well-designed application can cut down considerably on the number of times that the user has to refer to the help file at all. Consider these factors:

  • People (at least those who speak one of the Western languages) tend to read left to right, top to bottom. That’s why it makes sense to group the controls that indicate the end of a process (such as OK, Apply, and Cancel buttons) together in the lower-right corner of the application. Don’t make users hunt around for controls.

  • When entering data in a particular control is inappropriate, disable the control.

  • The use of tooltips to indicate the purpose of a control can be a great help to new users. The ToolTip control makes this easy to implement on .NET Windows forms. Tooltips can also help make your application more usable for users with special needs; screen readers, for example, will pick up tooltip text. Some users find tooltips annoying, though, so you might consider providing an option to turn them off.

  • For step-by-step processes, most users are accustomed to a wizard interface. It’s worth using such an interface, with clear directions on each panel, for such processes.

By paying attention to the design of your user interface, you can make it possible for some users to never need the help files at all. Watching actual users interact with your application can tell you whether you’re getting to this point.

end sidebar

Fortunately, there’s a free tool that makes this pretty easy to accomplish: NDoc (http://ndoc.sourceforge.net/). NDoc is actually the end of a process that starts with Appendix B of the C# language specification: “C# provides a mechanism for programmers to document their code using a special comment syntax that contains XML text. In source code files, comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede.” These comments are identified by being set off with three slashes instead of the two that normally introduce a C# comment.

You’ll find the XML tags used by these special comments explained in the XML Documentation section of the C# Programmer’s Reference. Table 12.1 lists the XML documentation tags that VS .NET can use for XML documentation. This list isn’t fixed by the C# specification; different tools are free to make use of other tags.

Table 12.1: XML Documentation Tags for VS .NET

Tag

Meaning

<c>

Embedded code font in other text

<code>

Multiple lines of source code

<example>

An example of using a member

<exception>

Specifies an exception that can be thrown by the current member

<include>

Includes an external documentation file

<list>

The heading row of a list

<para>

A paragraph of text

<param>

A method parameter

<paramref>

A reference to a parameter in other text

<permission>

The security permission required by a member

<remarks>

Supplemental information

<returns>

Return value of a method

<see>

An embedded cross-reference to another member

<seealso>

A reference in a “ See Also” list

<summary>

A summary of the object

<value>

The value of a property

Note

Although these XML comments are defined only for C# projects, several efforts have been made to extend the same concept to Visual Basic .NET (VB.NET). The VS .NET PowerToys download includes a VB Commenter add-in (www.gotdotnet.com/team/ide/helpfiles/VBCommenter.aspx) to give VB this capability, for example. In the “Whidbey” release of VS .NET, due in early 2005, VB.NET will have this capability natively.

As an example, here’s a piece of the code for the DownloadEngine class, with embedded documentation comments:

 /// <summary>  /// Replace a possibly null string with another string.  ///  /// </summary>  /// <param name="MaybeNull" type="string">  ///     <para>  ///         A string that might be null or empty.  ///     </para>  /// </param>  /// <param name="Replacement" type="string">  ///     <para>  ///         A replacement string to be used    if the first string is null or empty.  ///     </para>  /// </param>  /// <returns>  /// Returns the original string if it's not null or    empty, otherwise returns the replacement string  /// </returns>  private string ReplaceNull(string MaybeNull,      string Replacement)  {      if((MaybeNull.Length == 0) ||          (MaybeNull == null))      {          return Replacement;      }      else      {          return MaybeNull;      }  } 

Embedded in your code, these comments don’t do a lot of good for your customers, but VS .NET can collect these comments into an external XML file. To enable this collection, right-click on the project in the Solution Explorer and select Properties. Then select the Build page and enter a name for the XML documentation file, as shown in Figure 12.5.

click to expand
Figure 12.5: Activating XML documentation in VS .NET

After you’ve built the XML comments file for your application, NDoc can do its work. Figure 12.6 shows the NDoc user interface.

click to expand
Figure 12.6: Using NDoc to build a help file

You can select one or more assemblies to document and tell NDoc where to find the XML comments file for each assembly. NDoc will combine the information in the XML comments file with information determined by examining the assembly itself, and then build MSDN-style documentation for you. Figure 12.7 shows a part of the resulting help file.

click to expand
Figure 12.7: Developer-style help for a class library

For an even better developer experience, you can integrate your class library help files directly with the help for VS .NET. The Visual Studio Help Integration Kit, which I mentioned earlier in this chapter, contains the necessary tools and instructions for this process.



 < Day Day Up > 



Coder to Developer. Tools and Strategies for Delivering Your Software
Coder to Developer: Tools and Strategies for Delivering Your Software
ISBN: 078214327X
EAN: 2147483647
Year: 2003
Pages: 118

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net