April Reagan: The Future of MSDN Help

I can't wait.

I see my self as a novice dev and I find the help really frustrating.  At the moment you select which tech you want to search on and you still get hits back from other techs!

F1 sounds cool.

I would like clear exmples of how to use controls, they always seem laking, but I guess thats more about the content.

I think I agree with Dan a nice WPF viewer would good, but I think it would be nice to switch to a browser view.... too.

Yup , I would also like some ways to evolve HELP , mean u have really some gr8 ways than currently present, so that we can improve productivity ...
First i m gonna watch video.., & then will reply for some interesting ways...

Excellent interview. Very honest and I liked the direct request for feedback from us. Very good! Adopt this style and format for all interviews. This is what we need Interviews that are honest with failures and mistakes in MS organization, give at least an idea on future directions or some thoughts, ask for feedback and encourage discussions.
Furstly, I would like to ask about the help format in Windows Vista. How is that different and why can't that be used as a platform for the future? Why doesn't the group that owns help for future versions of Windows, merge or at least be in harmony with this new MSDN help group? If you want to deliver something down the road to ISVs then what a better vehicle than putting it in Windows vNext?
Secondly I would like to give my own experience with MSDN.
I very much like the breadth and depth of the content. You have an extremely valuable resource, especially compared to other companies. Time after time I have relied on MSDN even for purely educational purposes. Its covering of certain topics is complete andthorough. It is not only a spec, like other companies' documentation, but also like a book in a sense, very detailed .
I enjoy the table of contents and please do not do the same stupid thing as in Office 2003 that they made Help table of contents navigation very painful and have promoted only search. Search is important, but I like order in MSDN, an order in hierarchy that Windows and Office used to have but seem to lose release after release. Windows used to have a table of contents. Now in Vista it is this mesh of topics that you are first and formost meant to find using search. Similarly in Office the table of contents has been turned into an HTML page. Don't make the same, in my opinion, mistakes to make everything HTML based. The tree toc navigation is excellent, the Index controls are good. Desktop applications need to take advantage of the richness of desktop controls. Don't make everything a web application, where search dominates and where true advanced controls are not used. In fact, introduce more innovative user experience controls, such as multiple previews in the table of contents tree, etc. Not everybody is always randomly searching. Sometimes, you know what you want and where to find it hierarchically, only if the interface would tell you navigate in this way. Also, I might want to read up on a specific topic. The index and contents are useful in this regard.
Problems:
Yes, search is slow and not always relevant. But this is not the main problem. The main issue is that many users, for example university students, do not bother to install the large MSDN and rely only on the online version. However, the online version is complicated to navigate, as it does not offer the same rich desktop controls as the local one. It is very easy to get lost in the MSDN online pages, without a shortcut to navigate e.g. to the next and previous topics (alt+up and alt+down) and with every click having to refresh the page. Searching the MSDN site is not also as intuitive as using Google. So, users search using Google, read a page and then leave the site. Improve, therefore, the site navigation by adding AJAX or even optional Silverligh controls. Make the desktop version more rich in user interface controls, allowing you to zoom on the technology you wish to read about and do not improve only search and/or the speed parts. Make it easily and freely downloadable. What is this MSDN Library Subscription for example. Why should I pay an amount per year to get MSDN. In fact, I can download it even today, then why the subscription still? I understand MSDN subscription for products but for the docs. Why?
Next comes content quality. Although you can find good content on MSDN for managed development, most of the WIN32 topics have clear errors and are so old that one wonders if a complete rewrite should be underway. Reporting bugs is not easy (you have to sign-in to the Connect website, etc) and community content only adds but does not change a topic. Sending e-mail takes ages for the WIN32 team to fix a topic and even ignore you and never fix something for years and still waiting.
Students and beginners are also never cared for. Google is useful because it can easily find you sample code. But MSDN? No, they write and write and many time write these very marketing introductions, whilst I need a tutorial, some sample code and I would start my work.
Please think about your users. There are those who want to learn a technology thoroughly, like technology decision-maikers. Those people can use the table of contents and who cares if they read some "marketing" nonsence like "this technology increases your productivity, etc, etc" and "the Advantages for using that technology are ..., etc, etc" and "Legal terms" and "technical specifications". But there are also these users who want to get started quickly and they need some sample code with tutorials. I regret to say that especially for WIN32 and MFC unmanaged, no samples or useful tutorials are provided or are very hard to find. The samples in WIN32 are very old and contain errors. And don't get me started on COM development. If I am not an expert in the technology, MSDN is of no use. In addition, there are these users who are simply searching for a solution to one of their problems. These are the type of users you, I guess, are trying to help by improving the speed/search of your system. But MSDN should then aggregate content from the forums, the open MS bug databases and allow those users to submit bugs and discuss in forums, right from the MSDN interface if they would be satisfied. This is because such users are not covered only by the documentation in MSDN but require community features.
Finally, why don't you make your content directly editable like on Wikipedia. Users can submit changes and other users can vote on them and you will aprove them. Not Community Content but direct edits to the documentation. I would certainly improve some of the old WIN32 staff at least. Further, don't you think that it is time for all MSDN documentation to adopt the same tone, style and navigation structure everywhere. Now the Exchange docs for example are differently structured from the VS docs.
One thing is certain. In universities everybody uses Google. Nobody uses MSDN online directly. Think about and try to analyze the reasons behind it. It is not only because of search and the website experience, the content is also to blame. Give a beginner the IE's HTML reference from MSDN and then ask him/her to create a website. "No," he will say, "I will use Google to find sample code". But MSDN already contains some HTML sample code, you would say. But hidden in "marketing" docs and high-level long, very long, documents. Give any developer the MSAA reference and then ask them to right a screen reader. With no unmanaged tutorials on how to use COM and no sample code to get him/her started using MSAA then forget it. I think you should make a new rule: All sections should start (like many open source documentation) with a short tutorial and some code and then give the full decision-makers' oriented technical and marketing load later. Sometimes your docs are too wordy and seem to never get down to specifics. They sound like ISO standards that cover everything and don't actually help someone to quickly implement something.
      

one thing that would be nice:


keep info for older bits around and findable.

say for examplemI am working on a CE 4.1 device

then I do not want to see how to do stuff in WM 5.xx or 6.xx

I have to support and develop for a CE device and often find that the MSFT docs are jumping to the new version and forget the old one.

also the times where the docs tell me the signature of a method but nothing about how to use it, or why to use it.....

I think this has gotten better but....

just remember that with VS intelisense we have the signature already.... I am not looking in help to know that Foo(string Prompt)
is the method signature.... got that already.

sometimes things like:  in linq if i call say:

foo f = db.footable.Single(x=>x.id == 5);

what happens if there is no item with an ID of 5?
will this make "f" null ?
will I get a Linq exception ?

stuff like that ...

I have to say I agree with April's comment on performance. Way to slow to load the Help UI. Remember that the help app it is now competing with Internet Explorer which is usually already open on most people's machines. I think the simplest and best feature that could be added to Visual Studio is a search box like IE7's. And the results display either in the IDE reader or in an existing browser session (based on a setting).

I was expecting the interview to contain lots of denials about the state of MSDN Help. Well, April quickly put me into full reverse with her candid statements about the unfortunately situation, her suprising depth of awareness of the issues, and the reasons behind the status quo.

I'm delighted that we can expect a totally new Help system based on the-thing-we-cannot-name. My crystal ball says the killer app for the-thing-we-cannot-name is actually Help/Education/Training systems. I hope to see a framework, not just MSDN Help-centric, but something that is open, cross and big picture oriented.

I'd like to see a better integration between the MSDN help and the Visual Studio IDE for the various languages.

Being able to right-click a C++ function with a window that's inlined (like intellisense, but readably-sized) with in-depth information about the function would be great.

I am looking forward to the new and improved MSDN Help!

Here's an off-the-wall suggestion (not necessarily for April and her team but maybe for a clever dev out there with some free time):  a command-line interface to MSDN Help a la UNIX man.

Here's another:  write a Sidebar Gadget with MSDN Help.

My tuppence worth:

1. Relevence.  There is a simple reason why I tend to Google for most of my searches, a lot of the documentation I am seeking has either been removed from MSDN or is out of date.

2. Delivery mechanism. Personally I don't care whether the content is delivered via web pages, PDF, chm, sliverlight etc so long as I can find what I want easily and quickly.  However I'd probably prefer something not integrated with studio (other than support for F1) as I normally have multiple studios open and am happy only having one MSDN open.

3. Off-line availabililty. I work for a UK company who is owned by a Swedish parent - our net connection therefore goes through a proxy in Sweden and can be tempermental.  (I also do the occasional burst of development on a laptop which is only on the web when I'm within range of my WiFi connection at home.) If I install the MSDN library I want to be able to find the information I want whether I am connected to the web or not.  Perhaps the web can be used to provide for supplemental information or an effective errata list between MSDN releases. I'd like to see this information merged into the shipped MSDN library at every release which would keep the reliance on the web low. 

4. Install size. The MSDN library is huge - it is possible to filter by topic, would it be possible to split the installer to allow selection of which topics to install.  Perhaps if a topic was not locally installed then the help viewer could search the web.  It would be nice to be able to select say language and or platform and install topics from those.

5. Quality.  The quality of the library is variable - I suppose this is inevitable given the number of pages but particularly for some of the C++ API documentation the quality is very low - many topics almost read like stub pages which people have forgotten to expand.  We also have a standing joke in the office about the code quality of the samples - I know a lot of the code is fairly crude in order to keep the sample size down but its not a good example to give novices reading the MSDN trying to learn to code.  The library needs to be reviewed not just by technical authors but by area specialists who can write! (I'm a geek so I know how most programmers hate writing).

6. Searching/Library Organisation.  Whilst the searching capability has improved in recent years its still not easy to find topics in the library.  I've lost count of the number of times I've found something in the index only to find link to the page ends up with the equivalent of a http 404 error.  The organisation of the library takes some getting used to as well - it is almost organised for an experienced developer trying to refresh knowledge rather than how a new developer would like to find stuff.  A rule of thumb I have is that if you roughly know what you are looking for use MSDN otherwise use a search engine.

7. Legacy platforms.  I get the impression that once a new flavour of the month comes along then the whole MSDN library is recompliled to reflect that.  Currently it is .NET technology.  Previously it was Windows Mobile and CE.  The MSDN library team need to learn that there are still some of us splunking in old unfashionable tech who still need to look up documentation relevent to say programming C++ on windows 2000.  If I do a search for C++ material I don't want have to be reliant on searching the mobile C++ APIs and guessing whether the function works the same on other window versions.

8. Learning Resource. IMO the MSDN library has never been a learning resource.  This needs to change - it is criminal for someone spending a lot of money (in the UK about $1500) for Visual Studio 2008 and then having to buy books to learn the languages because there isn't enough introductory material in the help.  When I started with Studio back in the days of version 3 or 4 we also had Borland C++ in the office.  Both Borland and Studio were about the same cost, Borland came with buckets of documentation and introductory material, Studio came with a CD that wasn't any help.  Fortunately it wasn't my money so I bought some books.  If I had been a hobbist paying out of my own pocket I'd have stuck with Borland.

Thanks for listening!
Rant over

The idea that highlighting a keyword in VS and pressing F1 might actually become a realistic way of accessing the help is easily the most exciting thing about this. It's been years since I even considered that way of working, certainly not since the first VS.NET release.

Other than that, I'd like to have something like team annotations or MSDNwiki hosted on a local server, so my team could add comments and notes specific to our processes and projects.

Also, if you're not aware of it, the inimitable Verity Stob discoursed at length on the shortcomings of MSDN help in an article here: http://www.regdeveloper.co.uk/2007/03/08/msdn_gloom/

It's humorous in tone, but the points are all valid. Especially "yes, thank you, I know the function signature, but what's it for?"

I'd like to see more community interaction.  If you look at the PHP's help system on php.net/manual/, there's a LOT of community comments that really help explain things that some users don't quite understand.

Perhaps paying MVPs and authors to associate articles or comments or downloadable / working examples to various help entries would be also nice.

I'd also like to be able to place bounties on getting help that would then be added back to the community.  So, if I want to see an example for a class or method, I would like to place a "Help Wanted" sign on the class or method.  If it's really critical, I like to be able to pay for support on-demand (perhaps at $25 increments) that might be answered by either Microsoft or someone in the community.

I second the idea of better searchability and integration with existing content such as webcasts or other (possibly non-MS) online resources.

jlb0001 wrote:



I'd like to see more community interaction.  If you look at the PHP's help system on php.net/manual/, there's a LOT of community comments that really help explain things that some users don't quite understand.

Perhaps paying MVPs and authors to associate articles or comments or downloadable / working examples to various help entries would be also nice.

I'd also like to be able to place bounties on getting help that would then be added back to the community.  So, if I want to see an example for a class or method, I would like to place a "Help Wanted" sign on the class or method.  If it's really critical, I like to be able to pay for support on-demand (perhaps at $25 increments) that might be answered by either Microsoft or someone in the community.

I second the idea of better searchability and integration with existing content such as webcasts or other (possibly non-MS) online resources.

This is one of the reasons I continue to program in PHP. There are tons of examples and gotchas posted by the community that would otherwise take you hours to figure out on your own.

I'm still learning how to program in C#, but the only useful resource I have found has not been found on a single Microsoft run website. But other sites like codeproject.com. I take that back, there was one...

http://msdn2.microsoft.com/en-us/library/d3877932.aspx

Another item I dislike about MS help is that there are 5 languages that are documented and various .NET versions. An awesome addition to the current site would be to have an option to hide the languages I don't know yet and the .NET versions I will never write code for. There will probably besome sections in the TreeView on the right disappear, but that's fine, because thats all that should be relevant to me.

If Microsoft is wanting to expand their market share and get more people to use their products, they've got to realize that leaving out this kind of information to sell Microsoft Press books or Certified Training classes is going to continue to hurt them. Those resources are still an option and are still viable avenues, but not every one learns the same way and finds them useful (or affordable).

Just a quick reply to say that I'm reading all of your comments and taking note!  Do keep an eye on my blog for follow ups and questions for you all, and I all but promised Dan an update before PDC, so I'll see you again then

All:

Yes - love all the comments about making Intellisense tooltips 'smarter'..we've got thoughts along those lines as well

Agree that the content itself has room for improvement - I'm talking with the right folks about these issues



Some specific responses:

JChung2006 - I will look for and find a pointer to the Sidebar gadget that is running around out there to search MSDN - I'll post it to my blog when I find it; there had also been some internal efforts to get command line access to the library - I'll have to track that down and see where it landed.  Again, watch my blog for more details.

nektar - good question about Windows help, etc...currently help is a bit of a patchwork approach in even our biggest products. We will be talking to the windows client folks, and other product teams as we gain some traction.  Our initial focus is on developers, and ITPro, which have some scenarios which aren't typical in a consumer environment.  Certainly if we design with simplicity and flexibility, we will be able to serve the needs across the spectrum - the small and tidy 100 topic package up through the millions-of-topic-not-so-tidy assistance needs of, say, the MSDN library.  Just not everyone all in one release  Nods along to your other comments as well....

BSalita - I think your crystal ball is probably right, but we must start out on a small focused goal and build on that...it would be great if we can end up serving the far broader need that you point out

John E. Boy - have you got opposable thumbs for sale, then? My dog would love to purchase two but he can't work the mouse....besides that, great points

Typesafe - thanks for the reference!  These types of detailed customer verbatims do help to make a difference

jlb0001 - cool ideas!  we do have the community comments feature, but proportionately, we need much more involvement there!

invenetix - You might look at the learning resources here: http://www.microsoft.com/express/ - not to say that we shouldn't also be doing a better job in helping people learn to use the product from the start, we should, but in the meantime perhaps these resources will help you out.

AGAIN - thank you ALL for your comments - keep them coming and stay tuned to http://blogs.msdn.com/aprilr

- AprilR

I just want the dang help to work for C++....don't care about the look / feel / implmentation.
I just want to be able to search for "struct" or "namespace" or"CPoint" with a C++ filter and get something useful - even if off line.
Right now I can't (unless I use Google)
http://social.msdn.microsoft.com/Forums/en-US/devdocs/thread/26536e1e-c2f7-4164-96a6-97cf4d32887a