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.
I like it!
@RyanSL -- Great!
I love reading instructions, rules, guides, etc. MSDN documentation is great.
IMO, this change doesn't help much. Who is going to think to *scroll down* on the overload page? It's faster to simply click the links. Also, for complex overload permutations, having a huge list of all the parameters just jumbled together would be really confusing.
Here's some documentation improvements that could be made:
- Add **links** at the top of all MSDN-documentation pages that immediately jump you to the section of the page you care about (methods, properties, remarks, etc.) Why should you have to scroll?
- Update Visual Studio so it can generate MSDN-style HTML documentation directly from within the IDE. Make a wizard that does this. Eclipse/Java can do this with a few clicks, yet Microsoft gave up on the Sandcastle project with seemingly no explanation why.
This would need to be tightly (and seemlessly) integrated with MSBuild so it is easy to make it part of an automated build process. It is absurd how difficult is is currently to get automated creation of HTML documentation..
- Make the tooling support JavaDoc style comments in C# in addition to XML comments. I don't know if you noticed, but XML docs are really ugly compared with JavaDocs. Humans shouldn't be filling out XML by hand. Thank goodness the TypeScript team went with JSDoc rather than XMLDoc.
- Have feedback forms on MSDN that actually work / are monitored. Every time I give feedback on some piece of documentation that is either incorrect or lacks depth/code examples, nothing ever changes. Why ask for feedback if you ignore it?
- Make these comment sections support rich text, replies, and e-mail notifications. It's very silly that CodePlex, the Visual Studio extension site, and MSDN proper all have different comment systems.
I'm encouraged by this blog post that at least you guys are starting to think about this issue (documentation) some more. Both the VS tooling and the MSDN documentation quality have been really stagnant over the last 5 years or so (other than the new Metro-theme).
I'm not yet sure what to think about these changes. I like the idea of having all the information in one place, however the scrolling arguably is a bit annoying.
Bug: The Math.Round page has no anchor for the version information. The link is dead.
Bug: The String.Format page has an anchor "Format_Version", but the link points to "Format_Versions" => also dead.
What I personally would like to see is the added icons for the supported version in the overload table directly. For example, take a look at the improved overload page of the string constructors, and then compare it to the constructors table on the class overview page: msdn.microsoft.com/.../s1wwdcbf.aspx
The latter already has inline information (icons) to indicate support for e.g. Portable Class Libraries. Why remove that information? On the overload page, I now have to go down to the version information and read something like "Portable Class Library - All overloads without an SByte* parameter are supported". Then I have to go back up again and take a look at the overloads to filter out the ones with SByte* parameters in my head. I don't think this will be a practicable, useful workflow. So, in short:
P.S.: Somewhat unrelated, but: who is responsible for the Windows Runtime (Phone/Windows 8) documentation? We are constantly running into one of the biggest annoyances with the MSDN documentation over there: for example, in the .NET Framework documentation Task-based APIs are really nicely documented (see this: msdn.microsoft.com/.../hh159056.aspx). The return value documentation let's you easily jump to both the Task documentation as well as the type parameter documentation of the task. However, if you look at a similar example in the Runtime docs (msdn.microsoft.com/.../windows.phone.speech.recognition.speechrecognizerui.recognizewithuiasync(v=vs.105).aspx) you will see that it only links to the IAsyncOperation documentation, not to the eventual result of the asynchronous operation. There is no link to that actual result on that whole page so you have to manually look it up navigating through the tree, or even use Bing to find it. Please, pass on the suggestion to fix this, if possible. Thank you.
I really like this new documentation structure - I'm an old school developer who believes that the code isn't complete until the documentation has been written, and I can appreciate the amount of work that has gone into this new structure. I look forward to seeing more on other framework classes & methods.
I like having a 'top level' page where you can get a better view of a given method. The problem for me is that if you're in the middle of a long page like Math.Round it's difficult to know where you are in the document. I think this could be fixed by displaying the sub-sections in the treeview on the left (and keeping it in view as you scroll the main frame (yes, I know the frames have gone)).
I miss the 'proper' treeview in the msdn library - it just doesn't give the context that I'm after. I think its removal has made navigating the library a much harder task.
I'm not sure if the overload summary page will get much hits or if people will go straight to the concrete method page - you'll see in your statistics. Nevertheless it's an improvement, especially if an unknown or more complex method is involved.
Overall these are little changes and I think DrSpock11 points out more important topics. I'd like to back all his points!
Furthermore I'd like to see some kind of IntelliSense configuration - why not have a checkbox to indicate which documentation sections to show in the IntelliSense tooltip (e.g. the returns or remarks section). Especially I'd like to see the returns section in addition to the method description. And to avoid huge tooltips for lenghty sections you could also add some "maxCharactersToShow" option.
And I've also seen many comments on MS blogs complaining about your feedback / commenting system. This really is a mess and miles away from state of the art. Please listen to that and improve your system. Just think about the fact that I know that I need to keep this text in my clipboard because the first submit will fail due to some timeout issues. Come on MS, seriously?
I like this new page. Advantages I see are:
- If you don't want to scroll, just click on the links to the overload methods description.
- But, if you scroll, you'll have enough help to decide which overload to choose, without having to open 4/5/6... new tabs (which is annoying when you already have 10 or more tabs opened in your browser).
Also agree with the other points above.
That's definitely better: move the common information into one page (and for overloads—which of course should be very similar—there will be a lot) and save jumping from page to page to see enough detail (especially parameter names) to select the right overload.
The single suggest I would make is to move the exceptions section up (to immediately after the return value) so that is quicker to get to when you most know the method (ie. start with reference information and follow with the more descriptive information—including examples—that is less important when looking for quick reference.
On a separate subject while you're improving things: it would be helpful if implemented interfaces on a class' page were linked (currently they are just listed in the syntax summary); and there were quick links to jump to the properties, methods etc. sections (they can be quite long leading to a lot of scrolling).
I agree with DrSpock11 above: "Who is going to think to *scroll down* on the overload page?". Why not a qtip style (craigsworks.com/.../qtip) rollover when I rollover the overload link and put a very small quick example in the qtip. Clicking the overload link would take you to the full page.
Also, although the link to the example is a good idea and far better than before, i would still rather see an example in a qtip style rollover.
The colors at the "Overloaded Method Syntax" should be like the default color scheme on Visual Studio (C#). It helps faster identification of the return and parameter types and the method name itself.
Overall, I think this is a very good idea for providing useful and relevant contents for a specific topic in a single page. It makes me easier to find relevant contents without having to dig through so many unnecessary links.
I have one suggestion for "In this section:" navigation. I think it would better to just use a floating bar menu that would sticks statically no matter where user scrolls content. That way, it would make navigating contents easier without having to scroll to top page whenever user want to see different sections. I don't know the exact name for that floating bar menu, but I think you get the idea.
Looks great. One thing though, the icons in the left side of e.g. tables with constructor overloads are not spaced/positioned properly. Oh, and please consider splitting the "in this section / examples" section in two seperate paragraphs or aligning them in a table to reduce scrolling.
Aside from that, I think the general quality of the documentation on MSDN is very high.