The Help Guy

January, 2010

  • The Help Guy

    Help Authoring Tool (HAT) support for Help Viewer 1.0

    • 4 Comments

    As we've been ramping up the new the Help Viewer and its associated Help file format (MSHC), we've also been working closely with a few vendors to ensure that we have a good Help Authoring Tool (HAT) story for Visual Studio 2010.

    We have been working principally with the vendors that have historically been supporting Visual Studio's help system in the past (with Help 2.x). We are excited about the long-term growth potential of our new help system and welcome engagement with other HAT vendors as well. If you are in that category, please contact me via the contact form and I'll be glad to follow up with you.

    Below are listed the current Help Authoring Tool (HAT) vendors that currently support the Visual Studio 2010 Help format (MSHC). I have collected a little statement from each about their offering and how best to contact them at this time. They are listed below in alphabetical order for convenience sake (no indication of preference or quality, etc. implied):

    ComponentOne, LLC:

    "Doc-To-Help has always had a close relationship with Microsoft and the MSDN user community. You will always enjoy support of Microsoft’s latest technologies from their standard Help platforms to .NET developer technologies such as Help 2.0, Sandcastle, and .NET/XML transforms.

    Doc-To-Help will also always serve the community’s needs by addressing and supporting emerging technologies such as Visual Studio 2010, Microsoft Help Viewer 1.0, and beyond.

    If anyone is interested in a beta version of Doc-To-Help 2010 that works with MS Help Viewer, please contact Brad Keller at ComponentOne: bradk@componentone.com." Brad Keller - ComponentOne, LLC.

    Helixoft:

    VSdocman is a VS add-in for commenting and the automatic generation of class documentation from your C# and VB .NET source code. VSdocman parses the Visual Basic and C# projects (including ASP .NET) and automatically creates MSDN-like documentation, IntelliSense and F1 context sensitive help. You can edit your XML comments with WYSIWYG comment editor which allows inserting complex tables, links, pictures, class diagrams and others. Predefined output formats are HTML Help, MS Help Viewer, Help 2, HTML, RTF, Help&Manual and XML. Contact and other information can be found on product page." Peter Macej - Helixoft

    The Helpware Group:

    "mshcMigrate was developed by The Helpware Group in partnership with Microsoft and allows you to migrate older help content (MS Help 2 and MS HTML Help 1.x) to MS Help Viewer format (the new format for MS Visual Studio 2010 help). It takes various inputs including projects files (.hxc and .hhp), compiled help files (.hxs and .chm), and help folders. Outputs include .mshc/.cab help package files and .msha manifest files. The application includes several additional tools that allows you to test, install/uninstall, view the HelpLibManager.exe output log, perform API calls, and explore the help library data store. The utility is part of Helpware's FAR HTML v5 product set which provides advanced meta tag editing and TOC/Index editing for MS Help Viewer projects. mshcMigrate however can be downloaded separately and is free for personal use (see mshcMigrate licensing for further detail). Contact and support details can be found on the download page." Robert Chandler - The Helpware Group

    Innovasys, Ltd.:

    "Innovasys are currently finalizing updates to Document! X and HelpStudio to support seamless multi-targeting of Help 2.x (VS 2002 - 2008) and Microsoft Help Viewer (VS 2010) for both reference (assembly SDK docs) and conceptual documentation. Contact support@innovasys.com if you would like to take part in the beta." Richard Sloggett - Innovasys, Ltd.

     



     

    Sandcastle:

    Many people have been asking about whether we will be updating the Sandcastle toolset to support Help Viewer 1.0. I'm pleased to announce that we have posted a release of Sandcastle that now supports the MSHC Help file format used by Visual Studio 2010.

    The MSHC support was commissioned from ComponentOne, whom we thank for updating the code base to support this new Help format. We have additionally rolled in a variety of bug fixes since the last release in 2008. Please note the MSHC Usage Notes and Changes/bug fixes documentation links on the download site.

    MSHC support is currently limited to reproducing the VS 2008 look and feel and functionality within the VS 2010 Help Viewer. To achieve parity with VS 2010 look and feel will require more work and we encourage enterprising folk out there to take this on and contribute to the code base.

    See also the Sandcastle blog here.

  • The Help Guy

    What are we trying to accomplish with code signing content?

    • 4 Comments

    Help file content and web content have historically been significant attack vectors that hackers and viruses have utilized quite a bit over the last decade. We’ve seen significant issues with .CHM security issues since HTML Help 1.x was released. HTML based attacks in general are huge - we had a hack against our TechNet site just yesterday.

    So how do we prevent this sort of thing – even though the TechNet issue is a web specific example. Here are some of the constraints:

    ·         If anyone with minimal privileges can install or be tricked to install content with dangerous scripts, an Admin could potentially run unsafe content. On machines that are shared between multiple users, a user could unknowingly execute script that may have been installed by another user with lower execution privileges. In a review with the Windows Security group, they warned against the dangers of this scenario.

    ·         Even with Admin privileges, Admins don’t always understand the implications of what they are installing, so we still wish to provide notification that the action they are about to take is potentially unsafe.

    ·         With Self-branded content, there's higher risk of script being executed that is potentially unsafe – this, for us implies an even higher risk that we’ll need to protect the user against.

    ·         With Help Viewer 1.0 we are ultimately aiming at a broader user base than just Visual Studio users. We would like to become a replacement for both WinHelp and HTML Help 1.x.

    If you look at how security is managed for WinHelp today, its primary attack surface is around its macro capabilities. This is why in Vista and Win7, macros are completely disabled by default. You have to be an Admin to update the registry with some reg keys in order to re-enable these features.

    Additionally, with HTML Help 1.x, check out this list on Microsoft Help MVP Rob Chandler’s site:

    http://helpware.net/FAR/far_faq.htm#SecurityUpdates

    For better or worse, there’s a whole lot of security restrictions on help files now. The difference you may argue is that these are generally mitigated when a user installs a .chm via a setup program.

    The primary difference we have with Help Viewer 1.0 however is that a user can install content from media *or* the cloud, as well as updating from the cloud. Currently, this is mostly for Microsoft content, but we are not architecting to limit it to MS only content.

    ·         We ideally wish for a secure mechanism for installing and updating content regardless of the source location.

    ·         We need a mechanism that as a starting point helps guarantee against unsafe script being executed unintentionally, or at least with full knowledge that you’re opening yourself up for that.

    I think we agree that this is a pain (perhaps a necessary evil), and we’re open to discussion for how we might better address this in SP1, for example. Maybe the Admin applied reg key solution like WinHelp and HTML Help employ would be OK. I think what we’re trying to get across though is that, as its apparent with all the UAC hoopla around Vista and Win7, we unfortunately live in a general “unsafe” age and at a platform level we need to both educate users about the potentially unsafe actions they are about to take, and where possible prohibit if they are not in a position to make that kind of evaluation.

    How would you provide strong security given these constraints?

  • The Help Guy

    Working with signed .cab files

    • 7 Comments

    There's been a fair amount of discussion both in private emails and on the MSHelp3 Yahoo! group about the pros and cons of requiring signed .cab files for silent installs with the new Help system.

    As anyone who's been using Vista and Windows 7 knows, security is a pretty big deal these days despite all the headaches people feel it causes. Without security, you'll have even bigger headaches before you know it!

    Before long I will be posting some background on some of our thinking around this requirement. In the meantime, however, I wanted to make sure that those who have need of some of the basic details around signing their cab files have access to the general details.

    In addition, I'm providing some information about what you can do to test this out without having to purchase a certificate - you can create your own test certificate, which you can use for signing purpsoses on your own machine.

    Here's a page (again in the Links section, as well) describing the basic process. Have fun!

  • The Help Guy

    Known Issues

    • 0 Comments

    There are a handful of "known issues" with Help Viewer 1.0 that we will be shipping with at VS 2010 RTM.

    I will be maintaining a list of these issues and any updates via a page off the Links page.

  • The Help Guy

    Which IVsHelp Interfaces are supported in Visual Studio 2010?

    • 0 Comments

    Please see my page posted here.

    As I publish new pages, they will all be easily accessed via the Links link in the left-hand navigation pane.

  • The Help Guy

    Welcome!

    • 3 Comments

    Hello and welcome to “The Help Guy” blog!

    Why “The Help Guy?”

    I was aiming for just “Help Guy”, but it was already taken, though not accessible for some reason. Hmmm. Not very helpful.

    For me, THE Help Guy will always be Ralph Walden. I call him “The Father of Help” – primary driver and developer of the 3 main help systems that have had Microsoft platform-wide use to this day: QuickHelp (used in 1980’s DOS products, like the original Microsoft C++ Programmers Workbench, etc.), Windows Help (aka. WinHelp), and HTML Help 1.x. He even worked on the OS2 Help system while Microsoft was still involved with that OS.

    I could have gone with – wait for it – Ivory Boy. Nan Hickman, author of “Building Windows 95 Help” gave me this dubious appellation for some strange reason around 1995, back when Compuserve was still the rage and we had a lively WinHelp forum there. Ralph even gave me the perhaps more dubious distinction of naming an internal HTML Help system file after me: #IVB – used for storing Alias string information for context sensitive help purposes (See this interesting article for gory details.). Somehow Ivory Boy just isn’t that intuitive, though.

    Another alternative – Mr. F1 Help. A good friend of mine came up with that name back in the ‘90’s and I tried coining it for my consulting business at the time, but perhaps it’s a bit too formal. J

    So – “The Help Guy”. For the last 8 years that I’ve been working at Microsoft, I’ve worked a lot with Visual Studio Industry Partners (VSIPs) and their need to integrate their Help content with the various versions of Visual Studio that we’ve been shipping since around 2000. To many of them I’ve become “the Help guy.” Also, for many teams in Microsoft who have tried to work with that Help system (Microsoft Help 2.x) I’ve become the go-to guy for getting answers.

    Even before working at Microsoft though, I’ve always been passionate about “helping” people with Help related conundrums. I was even a Microsoft Help MVP for several years, and oversee the current Help MVPs now. I just can’t help myself!

    So there you have it.

    Why here?

    I’ve recently moved into a more intentional Partner Engagement type of role with Visual Studio 2010’s shipping-any-day-now new Help system – affectionately dubbed Microsoft Help Viewer 1.0. The meat and potatoes of my job is to ensure that all our Visual Studio partners are successful in migrating to the new Help system (and format), as well as to ensure that their needs and requirements are understood and represented to our team (LEX – Library Experience). Our team essentially owns the MSDN Library as well as the new Help Viewer, so what better place than http://blogs.msdn.com?

    A big part of this is making information readily available for our partners. One of the aims of this blog will be to post best-practice types of solutions, workarounds (where necessary), and to document odd bits that have not made it into formal documentation yet.

    Why now?

    Lots of reasons spring to mind for me. #1 being that my management would like me to. J However, I’ve been thinking about doing something like this for quite a while. The primary thing that’s been missing for me till now has been the right combination of whatever my current job responsibilities were, the team I was on, and the role I could play in the future of a Help system. Right now feels like the right job, the right team and the right time with the right Help system.

    My primary aim with this blog is to make information available on this new Microsoft Help Viewer 1.0 platform, especially as it relates to Visual Studio 2010 Help integration. This is critical as it is an entirely new system and way of doing Help. There are and will be growing pains. This is a 1.0 product.

    I have a secondary aim though as well – to provide a locus for entertaining, discussing, and opining on any issues pertaining to Help technologies past, present and future. Hopefully, this will be more than just my meandering thoughts… I’d love for this blog to become a place where great ideas for the next broadly public Microsoft Help system are published (by you gentle readers, and me) and come to fruition. To that end, I welcome suggestions on topics you would like to see addressed.

    What next?

    I will be posting some updates on the status of Help Viewer 1.0 in recent VS 2010 builds, Known Issues, etc. Those types of updates will come pretty regularly at least from here through VS 2010 RTM. However, I hope to continue those types of updates past RTM as well.

    As new issues may surface and workarounds become available I will be posting on these as well.

    Now what?!

    Nothing – just checking if you got this far. ;)

Page 1 of 1 (6 items)