Adding Help to Visual Studio 2008 application with Dr.Explain

Feeling that, although not fully completed, it was about time to move from the core development of my first C# application (Accommodation Management System) I found that there were a number of areas I needed to investigate/learn - one of these was creating the Help feature of the application.

I trawled through the Net, like you do, trying to find a glimmer of guidance on what you use, where you start from, tutorials, anything and everything with relation to Visual Studio (preferably 2008) and Help files.

I eventually turned up with the usual MSDN pages and other sites with their wares/apps.

Firstly I tried the MS tutorials (in conjunction with Innovasys Help Studio Lite) and although HelpStudio Lite potentially seemed very impressive I felt somewhat despondent by the way that the help files had to be 'integrated' with the Visual Studio project - several command line entries and additional code that to me as a recent beginner of C# made me reel - there had to be a better way even if it meant not having something that wasn't quite so fancy as MS Help 2.

Soon I was surfing and reading more entries but still it was very hard (if not impossible) to find anything that shouted Visual Studio and Help files/generator (or not at least as I was looking for). Soon I decided that I had trawled enough and I have found a select few possible apps to help and read through them and downloaded their software to trial. It wasn't long before I began to realise which appeared to be offering me hope.

Dr. Explain
Although there was some information I found it to scarce for me to again understand whether this would do what I wanted - or probably more likely would I be able to understand what I would need to do with it for it to give me the end result (a simple help generator that I could 'link' to my project/app).
Well like any good new experience I've had my moments of frustration not being able to understand what certain things did and what I had to do through Visual Studio but since installing it late last night (less than 24 hours ago) I have had my moments of feeling wonder and bliss at finding something that I have been able to use that meets my requirements (yes its quite possible that I am not using it to its full extent but I feel that I have a good base in which to explore and get more out of it).

How does it work with Visual Studio 2008?
... I can almost hear you say (well I certainly wish I could have heard someone say for me several days ago).
I was fortunate to come across some interesting posts

Dr.Explain Mini-Review a 'mini' review by tinjaw on the DonantionCode.com website.

Help for controls with VB .NET from the Help Information website

The first inspired me and the latter with its screenshots/examples gave me some idea of what I should be looking at and even doing.

My steps (in brief)

1. When creating your help file (CHM) with Dr. Explain ensure that all the objects that you want to reference from your project/app has an Anchor string - this is available when you click on the object and is under the Properties section just below the Title property).
2. Save your CHM file by clicking on the Generate CHM icon (the second/middle icon with the green up arrow on the toolbar).
3. Ensure that you have the correct path for the HTML Help Workshop folder (otherwise download/install before proceeding).
4. Click Start export and you will be asked to browse where you want the CHM file to be saved.
5. In Visual Studio drag a HelpProvider component from the Toolbox onto your form.
6. Click the on helpProvider1 component(which should be under your form) and open its properties window. Set the HelpNamespace to the location of the CHM file you created.
7. Select a control on the form which created an Anchor reference for.
   
8. Change the setting for 'HelpKeyword on helpProvider1' to the format [Window Topic name].htm#[Anchor name of Control] (eg. 'main_screen.htm#address').
9. Change the setting for HelpNavigator on helpProvider1' to 'Topic'.
10. Select the form and change the 'HelpButton' setting to 'True' - this will then show the '?' icon at the top-right of the form.

Run your project and you should be able to select the '?' icon and then click on the control that you changed the Help settings of and the Help file (CHM) should load with the related Help topic (eg. 'main_screen') with the relevant object showing near the top (eg. 'address') - just like a webpage. F1 key also works the same way but will actioned the focused object. As this was problem then to get the form (and thus the main part of the Help Window showing as opposed to the individual objects) I added a Help option in my MenuStrip with the following code for the item when clicked:

private void helpContentsToolStripMenuItem_Click(object sender, EventArgs e)
{
Help.ShowHelp(this, helpProvider1.HelpNamespace, HelpNavigator.Topic, "main_screen.htm");
}

Final thoughts on Dr. Explain
Again its early days but I am very happy to have found Dr. Explain as I have now been able to implement a Help system into my application.
Maybe I'm easily amazed and having not explored the other Help 'generators' in part or full I'm not sure whether it is part of the other packages but when I first tried to add a Window and it launched the capture utility (and had a couple of miss tries - the first locked up and the other was a mouse action that gave me the wrong result) and then presented me with the image I was wowed by it labelling with its objects almost all of the objects from the Form it captured - I do love things like this that make work so much easier and fun.

tinjaw has given a much more in depth look at Dr. Explain and I'm not going to try to do anything like that. I'm very happy (as you probably guessed) but I know at the same time that over time and given time to ponder and compare I could probably could say issues that need addressing but what software doesn't.

Hopefully this has proven usual even if its just for one person.


Richard
Visionscape