A first hand look from the .NET engineering teams
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.
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.
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.
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:
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.
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.
For what it's worth I think it's a good idea to update the documentation, but the only issues I have with the old one myself I don't see addressed at all.
a) List all the exceptions that a method can potentially throw, and/or label the methods that are likely to throw because of IO or network errors in the long run.
b) List algorithmic complexity where it's appropriate, or at the very least label the methods that will be very slow for some inputs.
c) Trim your examples - often the examples are too long and don't even show common use case. Some examples haven't been updated to use new idiomatic constructs such as using(), and best practices such as variable naming conventions.
Keep up the good work, need to keep quashing all those low-content pages so there isn't 3 to 5 clicks just to see a simple method example. Always a fan of making MSDN more concise!
The couple of examples I checked look good, they have lots of description and examples. But they were on relatively simple and easy to understand routines. My problem with the MSDN documentation is the complex classes that have lots of methods, fields, properties and etc but that have almost no description and no examples. How are we meant to understand these classes, to know when to use or not use them, and to use them properly? Some examples:
UITestControl Class msdn.microsoft.com/.../dd433980.aspx
Often, the overloads are "convenience" overloads. However, there is no documentation about which settings are used. That is what I am missing all the time.
For example, is string.Compare(a, b) the same as string.Compare(a, b, true) or string.Compare(a, b, false)? In this case I would assume the latter, but often this is not as obvious.
I like that more information is being added to the overload list pages. It would be really nice if more info, especially examples, could be added to the actual member/method pages.
This is the first of a three-part response.
Thanks very much for your feedback so far. We really appreciate everyone taking the time to submit your thoughts not only about the content of the overloaded method documentation, but also about the overall structure and presentation of our documentation.
Our publishing system uses reflection to auto-generate managed reference content, which it combines with authored content. For example, in the overload list topics, the table immediately beneath the Overload List caption is auto-generated by the build. At the moment, we’re experimenting with improving these web pages without making significant changes to our publishing system. In the case of our four example overload list topics, we’ve largely duplicated this auto-generated table by adding our own Overloaded method syntax section, since we wanted to add return value and parameter names to each method signature. In any case, where your feedback has concerned the structure and presentation of the documentation, or has focused on extra-documentation issues such as building your own HTML documentation, using IntelliSense, or submitting feedback, we’ve passed it on to members of the appropriate team.
The current build system and MSDN page design do not support a single integrated page for all overloaded methods. We’ve worked around this limitation by putting all of our authored content in the Remarks section. The downside is that we’ve lost some features that the build system provides, such as color-coding, icons, and collapsible sections. With build support for overload list topics, these limitations would disappear.
[Peter Kuhn] Thanks for catching those dead links. We fixed them for next week’s documentation refresh. We’re forwarding your feedback on the Windows Phone documentation to the writers on that team.
[DrSpock11, Peter Kuhn, John Goldsmith MVP,MgSm88, Maximillian Haru Raditya] Many of the objections or issues raised in your comments could be addressed by adding build support for some new features, and your feedback here helps us request a change in the way overload list pages are built. For example, something like a floating tree view containing a table of contents (what is now the “In this section” section) that is always visible in the left portion of a page and and that indicates your current position would enormously help with both orientation and navigation. It would also either eliminate or reduce the need for scrolling.
Other changes will require changes to both the way we author overload topics and the way the build system presents them. For example, the comment about complex overload permutations producing a long list of parameters is a good one, and is an issue that concerns us. We’ve tried to present a possible solution in the String constructors overload list page, since its parameters tend to fall into two distinct categories, based on whether the constructor uses a pointer.
This is the second of a three-part response.
[DanielRose] One of the nice features of this design is that it brings the issue of default parameter values to the fore for the convenience overloads. For example, in the DateTime.Parse method, we’ve included a Default value entry for each parameter that shows the default value of the parameter. Another nice feature of this design is that it allows issues to be addressed that are unrelated to individual overloads, such as the problem of Single to Double conversion in Math.Round.
There remains the question of why bother –as DrSpock11 succinctly put it, “Who’s going to think to scroll down? It’s faster to simply click the list.” That, in fact, had been our assumption up to this point, and is the reason that the overload list topic has existed in its current form since the .NET Framework 1.0 through the current version. But a substantial proportion of our negative feedback (we’d estimate its overall volume at anywhere from 25 to 50 percent) comes from customers who, for one reason or another, don’t want to click the list. Some comments are clearly from inexperienced developers who don’t understand what overloads are and don’t know why you would want to click the list. Other comments are from experienced developers, who want to find the item of information they’re looking for (usually return value, parameter, or exception information) without clicking the list. So clearly, some rethinking of how we handle overloads is in order.
[DrSpock11, Tom] When we get feedback, we route it to the writer who owns a particular topic. Whether individual feedback items are addressed, of course, depends on a writer’s overall workload and on the volume of feedback. But the fact is that we do take customer feedback very, very seriously, we do spend a good deal of type reviewing customer feedback, and we do use customer feedback to make numerous improvements in the documentation. So we encourage you to continue to submit feedback to us using the feedback mechanism.
[AdrianHHH] We understand your frustration with minimalist documentation. In this case, the APIs are not owned by our team, so we can’t simply add detail. But in general, when you feel that an API or a type is under-documented, by all means provide feedback!
This is the third of a three-part response.
[Gleno] As far as we know, we’ve documented all of the exceptions that methods in the Base Class Library can throw, other than exceptions that can be thrown by any method and therefore are not documented by design. (For example, any method call that allocates memory can throw an OutOfMemoryException, and calling a method on a null reference always throws a NullReferenceException, but these are never documented.) However, we do occasionally miss things, so if you encounter an undocumented exception, please let us know, and we’ll investigate and add it to the documentation. The same is true for algorithmic complexity (we try to add notes to the documentation for methods that are likely to offer poor performance under particular conditions, but identifying them is not an exact science) and the staleness of examples (keeping an enormous code base current is a daunting task). So by all means, please do provide feedback – it really helps us prioritize our work.
Senior Programming Writer
Common Language Runtime User Education
What about F# snippets of examples?
i want to work for you.would you give me some work
I think the MSDN documentation has suffered massively since the removal of the "Classic" view. It is so much more difficult to navigate between items and the general ease of use has drastically decreased. There is even a thread on UserVoice requesting that this view be brought back.
Please consider bringing the 'Classic View' of MSDN back. The 'Lightweight' version doesn't cut it.
That's a great site.Anyone can get help from this site.
I like the consolidated list of multiple methods on the same help page. Individual pages for each overloded method hide content in boilerplate. Please document string.format and date format wiith a table giving three columns 1) data type, 2) sample value and format string and 3) output. The code samples are nicer in the sample pages listed. Please consider more real world ones for the asynch keyword, such as a simple sliding window packet based protocol with timeouts, out of order packet handling, and lost packet handling.
I think one of the worst things you ever did was shove the "Remarks" section so far down it takes me ages to get to it. But that new page for overloaded methods is dead sexy and makes up for it.
Excellent Post. Also visit www.msnetframework.com