Documenting .NET Components

I feel the need, once again, to preface this entry with a few disclaimers. One: this is my opinion. Two: I'm not just saying that this stuff sucks, I'm trying to be constructive with the criticism so that problem areas can be improved. Three: It's a much-needed venting of frustration. Please interpret as such.

The past week has been a crash course in building Combined Help Collections for MSHelp2. For the number of people building .NET components out there, there seems to be a severe shortage of information. Fortunately, third party tools and Microsoft's own code come to the rescue one again.

So you want to know the best way to learn how to integrate with VS.NET's help? Same way you use Reflector to learn how stuff works in .NET... decompile it. Helpware's FAR can decompile any MSHelp2 collection into the source files. You can then take those files apart for examples on how to create "See Also" sections and what-not. Best way to go IMO... just don't rip off content. That's what <MSHelp:link> tags are for ;).

MSHelp2 is a pretty slick system. It has a bunch of nifty ways that it hides and filters code based on certain tags. Once you get the hang of it, editing the files is a snap. My favorite editor? You guessed it: FrontPage 2003. It's quick, it's easy, and it has Dynamic Web Templates. A big plus for keeping the layouts simple.

Unfortnately, the list of what I don't like is longer than the list of what I do. I'd build some tools myself, but I don't have the time. First on my "Man this is more difficult than it has to be list" is Helpware's FAR. It's a great tool, and it gets the job done, but it's as complicated to use as MSHelp2 itself. The UI is very poorly organized, to put it nicely. It's fairly obvious that the developers (not to knock them, since they're fellow MVPs) are conflicted over it's purpose. The different utilities pop up in separate windows (instead of a unified Workshop interface) and it's INCREDIBLY difficult to navigate. I spent my first 3 hours with it banging my head against the desk. At the very leats, I should be able to set a profile saying whether or not I'm working the the old-school CHMs or the new HxS files.

Also, working with the HxT (Table of Contents) files is way harder than it has to be. I'd like to see the UI cleaned up a lot. Also extremely confusing is the fact that you have to generate a completely separate set of collection files if you want to plug-in the help file into other collections (Like the MS.VSCC). The documentation on this is completely confusing for newbies, and it took me almost 2 days to completely figure it out. I'd like to think that I'm pretty smart, but it kinda sucks when your tools make you feel like a complete moron. Makes me want to be a carpenter... my hammer doesn't make me feel stupid.

But the biggest problem lies, again, with Microsoft. To use FAR and NDOC, you have to install the Visual Studio Help Integration Kit 2003, aka VSHIK. The problem is, their documentation about writing documentation is HORRIBLE. Ironic, isn't it? It doesn't even follow the conventions that the VS.NET docs do. They combine several subjects into a single topic, and then they don't even explain that part very well. There is not a hierarchial reference of HTML tags for use on MSHelp2 HTML files, nor is there any guidance on how to create layouts. Basically, IMO it was not written with the end user in mind, and to that end, it's practically worthless. I'm sorry VSHIK team.... the compiler is great, and you guys are trying. I won't mince words: you have more work to do.

At the end of the day, it's no wonder why more .NET components do not have integrated help. Microsoft makes it easy to build the components, but they make it next to impossible to get them to commercial quality. At least not to the little guys that make up the bulk of the potential in this market segment. Microsoft supposedly wants to facilitate the creation of rich vendor markets, but the only people they focus on are the people who write bloated components that can afford to have someone at the MS campus 2 weeks a month to work with them. It's not enough.

At any rate, the documentation is pretty much done, and it's time to move to the other place where MS dropped the ball: Installers. And don't talk to me about WiX either. It's not ready for prime time yet. It will be really neat... someday. Right now I still have to sumo-wrestle with VS.NET's deployment projects to do what I need them to do.

I hate that I always want to make everything better. Because part of me wants to drop what I'm doing and spend three weeks putting together a dirt simple tutorial for building Integrated Help, in terms that people that don't hold BAs in documentation can understand. But I don't have the time. At least, not if I want to get ScrollingGrid 2.0 out before the end of 2004. At least I won't run out of things to do for a while. I don't want to knock the guys that came before me too hard, but the industry has been around for 20 years, and this is where we're at? It's easy to write software, but it's next to impossible to build a decent business around it?

Geez.