{"id":5731,"date":"2010-01-25T14:17:26","date_gmt":"2010-01-25T14:17:26","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/bharry\/2010\/01\/25\/help-with-help\/"},"modified":"2018-08-14T00:20:41","modified_gmt":"2018-08-14T00:20:41","slug":"help-with-help","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/bharry\/help-with-help\/","title":{"rendered":"Help with Help"},"content":{"rendered":"

Over the past few couple of months, I’ve seen some negative community feedback on the new help system – not universally, but enough that it’s been concerning me.  The truth is, though, I’ve been so busy with the performance work that other than pinging the help team every once in a while to make sure they were hearing the feedback, I really haven’t had time to understand it.\nWhen I was in Redmond this week, I finally got a couple of hours to sit down with the help team and the new TFSServerManager app I’m building and play with it.  I can now say that I really don’t understand the intensity of some of the feedback.  I’m hoping some of you can help me.\nBefore I launch into my perspective, let me give you some context.  When I spent the vast majority of every day typing code, I used help quite a lot (most of it was pre-IntelliSense days, so I really used it a lot).  At that time, my primary mode of using help was the keyword index.  Search sucked and the keyword index was by far the fastest way to find what you were looking for.  In more recent years I find IntelliSense has dramatically reduced (but not eliminated) my reliance on help.  Although, I must say, as an aside, that in 2010, my reliance on help is dwindling even further because it now finds members that match by arbitrary substring.  Anyway, in the last few years, MSDN has been my help system – yes it doesn’t work when you are offline, but I find I don’t do all that much offline programming and I get by without it.  So, the truth is, I haven’t used (or even installed) VS help in several years now.\nSo, please take that as context for all of my comments here.  Your experience is probably very different and that’s what I’m hoping to learn from.\nSo, I sat down to try out the new help system.  I wanted to try both online and offline help.  Installing local help was really easy, I just ran the help manager from the Visual Studio Start menu folder, picked the subset of help I wanted locally.  It then proceeded to download the help in the background.  In the mean time I played with online help.  When the download was done, I played with local help.\nThe first time I launched help, it was really slow.  After that, I had occasional occurrences of slowness but not often and by and large help was WAY faster than using MSDN.  The help system did a reasonable job finding the help topic I was looking for but definitely had some issues (see my list of issues below) and all, in all I found the experience to be quite reasonable and better (except in a couple of ways) than using MSDN directly.  I think with a few improvements that the help team committed to making before we ship, I’m a convert to the new help system and will use it instead of MSDN directly.\nNot everything was rosy and I don’t know that I can remember every issue I hit (the help team was watching me and taking notes, so I know they got them all but I just have my memory right now on the airplane :)).  Here’s the notable things I remember.  I’ve put them in decreasing order of importance (in my book)…<\/p>\n

    \n
  1. I saw several issues in the F1 resolution rules (like mis-capitalizing something), causing what I’m looking for to not be found.  I think most of the rules issues I found could be hugely mitigated by falling back to a full text search result when you can’t resolve the keyword rather than going to an empty “blah not found” page.  The help team has committed to doing this for RTM. <\/li>\n
  2. Opening a new browser tab every time I hit F1 leads to painful tab management.  I don’t like getting browsers full of dozens of tabs.  They pointed out to me that I can change my browser settings and have it reuse the existing tab for everything, but that’s a global setting, and the truth is, I’m happy with the behavior I get for most everything but help – so I really don’t think I want to do that.  I’m not sure what they can do about this without writing specific code for each browser to get the behavior that I want. <\/li>\n
  3. The clipping of many topics in the left pane (table of contents) with no resizeability is pretty ugly.  You could hover over a topic and see a tool tip with the full string, but the clipping of topics seemed very unfortunate and inhibited browsing.  I’d like to see the table of contents resizable horizontally so I can browse topics with longer names – maybe even a horizontal scroll bar but I can’t say for sure that would be an improvement without trying it. <\/li>\n
  4. The inability to scroll the left (table of contents) and right (topic content) separately in light weight mode is kind  of a big deal.  It makes it much harder to maintain context and navigate around.  I think they are going to address this. <\/li>\n
  5. The lack of a keyword index is unfortunate but not damning.  I’ve seen a lot of feedback on this particular point in the community and I can’t understand the intensity.  I don’t think the lack of it slowed me down, though I agree it would be a nice feature (and the help team has heard that feedback and is busy working on a post RTM add-on to provide it). <\/li>\n
  6. The table of contents tree behavior in lightweight is less than ideal but usable.  To make the lightweight help pages render MUCH faster, they’ve greatly simplified the management of the table of contents tree.  The result is that it’s faster to get to a topic but it’s harder to see context around it and to quickly browse around because you can’t see the whole tree and us + and – to expand\/collapse.  I found myself hitting the browser “back” button quite a lot.  I didn’t hate it but I can see how for some scenarios it’s not what you want.  To be honest, I still can’t decide whether I like the “lightweight” or the “classic” views better.  There are different trade-offs. <\/li>\n
  7. Launch speed is sometimes a bit slow.  As I remarked above, this was particularly true of the first time.  I went back to try and repro it a little while ago and I couldn’t so I’m not sure it’s a big issue. <\/li>\n<\/ol>\n

    So, that’s my brain dump on things that could be better about the new help system.  The new help system has a lot of benefits and a number of areas for improvement but my assessment is that, overall, it’s pretty good.  I’ve seen feedback from some people who I think would describe the new help system as very bad but I don’t really understand it.  Can someone help me?\nOne thing I will say is that I’ve been looped in on a few thread\/forum posts between members of the help team and some people in the community with feedback and I don’t think we’ve always handled the feedback very well.  I saw one thread this week where I would say we were down right condescending.  I’ve given very strong feedback to the management of the help team about that and I think they are taking steps to deal better with the feedback and ensure we are listening, keeping an open mind and doing everything we can to address concerns.<\/p>\n

    Brian<\/p>\n","protected":false},"excerpt":{"rendered":"

    Over the past few couple of months, I’ve seen some negative community feedback on the new help system – not universally, but enough that it’s been concerning me.  The truth is, though, I’ve been so busy with the performance work that other than pinging the help team every once in a while to make sure […]<\/p>\n","protected":false},"author":244,"featured_media":14617,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[4],"class_list":["post-5731","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized","tag-visual-studio"],"acf":[],"blog_post_summary":"

    Over the past few couple of months, I’ve seen some negative community feedback on the new help system – not universally, but enough that it’s been concerning me.  The truth is, though, I’ve been so busy with the performance work that other than pinging the help team every once in a while to make sure […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/posts\/5731","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/users\/244"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/comments?post=5731"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/posts\/5731\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/media\/14617"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/media?parent=5731"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/categories?post=5731"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/bharry\/wp-json\/wp\/v2\/tags?post=5731"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}