.NET Framework Documentation Improvements

Brandon Bray

The CLR documentation team has been busy responding to feedback and making updates and changes to the .NET Framework documentation in the MSDN Library. We would like to tell you about the most recent set of document updates, which were published earlier in February.

Performance content

We have received extensive customer feedback regarding the importance of performance in .NET Framework apps, and we wanted to make it easier for you to find relevant content.

As a result, we’ve reworked the existing performance and reliability topic to include more performance guidance as well as links to performance analysis tools and technology-specific performance content. We’ll continue to improve this documentation area in the coming months.

Do take a look at the revised Performance in .NET Framework Apps topic. Please give us your feedback to help us choose which area to focus on next.

Overload list topics

We are experimenting with a new approach to document methods that have overloads. These pages have been an area of consistent feedback. We have heard that the current approach requires too many clicks to get to the overload page that you want. We are piloting this new approach with the following method overload pages:

 

Let’s take a look at why we decided to try something different with these pages. In the MSDN Library, our current documentation design for overloaded methods and constructors uses an overload list to provide summary information and links to individual overload pages. Typically, these pages include just the overload list, requiring you to choose one of the overloads to find any technical information for that method beyond just the overload signatures. For example, the following image shows a portion of the String.Compare page.

 

image

The overload list provides an abbreviated syntax for each overload (without its return value or parameter names) and a brief, typically one-sentence description. The page was designed to provide just enough information for you to select an overload, and then follow a link to detailed documentation about that overload. However, we have heard many of you ask for more detail on the overload page, such as individual parameters, return value information, and examples.

Until now, our strategy has been to direct you to the detailed information on the individual overload pages. We had done two things to achieve that goal:

  • Added the following note before the overload list: "This member is overloaded. For complete information about this member, including syntax, usage, and examples, click a name in the overload list."
  • Reduced the visibility of these pages by ensuring that they do not appear in searches and member lists.

However, even after those changes, we were still hearing requests for more information. To address this issue, we would like to solicit your feedback about the new approach we’re trying out. As already stated, we’ve revised four overload list topics to provide complete documentation for all the individual method overloads. In each case, the overload list topic should serve as a one-stop source for information about that method and all its overloads.

Note, though, that our build system does not yet support this revised format. Because of this, the boilerplate text "This method is overloaded…" continues to appear on these overload list pages. At a later time, we will remove that text.

The expanded documentation is in the Remarks section and includes complete method syntax, parameter and return value descriptions, a list of exceptions, a table to help choose an overload, extended discussion of using the method, and at least one example for each overload.  Here are a few screenshots from the updated String.Format overload page to give you a better idea of the information that you can expect on overload pages with this new approach. Feel free to check out the whole page for yourself.

image

image

image

 

 

Tell us what you think of this approach. Does it make it easier to get to the information you need? Do you have any suggestions for further improvements? We look forward to hearing from you.

Follow us on Twitter (@dotnet) and Facebook (dotnet). You can follow other .NET teams, too: @aspnet/asp.net, @efmagicunicorns/efmagicunicorns.

0 comments

Discussion is closed.

Feedback usabilla icon