
	An ordinary VB developer shares his own successes and failures FREE to registered subscribers only.

VBInfoZine interviews Peter Macej, the author of VBdocman.NET

Here is a transcript of my phone call with Peter Macej, the maker of VBdocman; an automatic documentation generator for Visual Basic .NET and Visual Basic 6.

Palo: What's VBdocman.NET all about?

Peter: The idea behind VBdocman.NET leverages the well-known fact, that technical documentation (if any) is almost always made obsolete by the actual source code it documents. I'm pretty sure that all the developers out there would agree that maintaining technical documentation is not a funny task. However, what most good developers do is that they comment their source code. VBdocman.NET simply takes the developer's source code comments and generates a professionally looking, context-sensitive help files in any of the supported formats. And because the documentation is generated out of the actual source code comments, it will never get obsolete.

Palo: But the source code comments have to be in a special format. Isn't that limiting for the developers?

Peter: Not at all! Sure, the comments have to comply with the VBdocman.NET rules, but that actually helps to structure the comments more cleanly and uniformly, which is a good thing.

In addition, inserting a comment to an existing procedure is a snap - you just invoke the code editor's context menu, select "Add VBdocman Comment" and you're done! VBdocman.NET analyzes the current method declaration and generates the necessary documentation elements for you.

By the way, VBdocman can use its own comment formatting tags, or it can generate and parse the "almost standard" XML formatting tags C# programmers already know and love.

Palo: That's interesting, but I've heard that in the next "Whidbey" release of VB.NET, there will be support for XML-style comments built directly into the VB compiler. Why should I buy VBdocman then?

Peter: It's true that Whidbey will support XML comments. But the only thing they will be used for is generating XML documentation for IntelliSense and Object Browser. This is fine, but you still miss the main thing - the context-sensitive help. VBdocman .NET does it all. It generates complete help system and integrates it seamlessly into VS.NET with all the features like table of contents, index, filters…the list goes on. And, of course, everything is context-sensitive.

In addition, the help can be generated in several formats including Help2 (the latest format used in Visual Studio .NET), classic HTML Help 1.x (CHM), pure HTML, XML or RTF.

And, of course, the XML comments used by VBdocman today will be fully compatible with XML comments supported by the future "Whidbey" VB compiler.

Aside from Whidbey, there are still lots of VB6 programmers having to maintain and enhance VB6 code. And they don't have any future "VB6 Whidbey" release before them. But we're still taking care of them - with our VBdocman's VB6 edition, they have all the features of VBdocman.NET within their familiar VB6 IDE.

Palo: I've developed a component for Visual Studio .NET. Can I generate a help file that is integrated into the Visual Studio .NET help collection?

Peter: Of course you can. And, by the way, if you'd like to do it without VBdocman, it's a tough job.

If you want to use all the features of VS.NET help system, you must use the Help2 format for your help files. But unlike HTML Help 1.x, creating and especially deploying Help2 documents is just plain too difficult. Microsoft describes this process on 11 pages; you must perform several "low-level" steps and use several tools. In addition, if you want your help to be context-sensitive, you must follow yet another set of special rules. I think that this will discourage many developers from using the Help2 format.

With VBdocman .NET, however, all of this hard this stuff is done for you automatically. VBdocman.NET creates complete help systems, ready to be deployed on your customer's machines. It even ships with a small command line utility that you can include with your setup package and that will properly install and register your help files on the target machine.

Palo: How is that that a man from Slovakia enters the "online world" developing and marketing his own software?

Peter: VBdocman started as my own personal tool back in 2000. At that time I worked on several different projects and my employer required me to write technical documentation in RTF format. It took me two weeks to write the docs and it was quite boring! After that, my employer decided he also wants HTML Help documentation.

The sad vision of another extra weeks spent creating documentation forced me to write a tool that will generate it for me. I was hoping that I could finish the program in a month or two.

What a mistake!

It took nine months until the first VBdocman version was born. Around that time, I've realized that there might be other programmers out there that will benefit from using VBdocman. This is how my software business was born. Nowadays, I've been working fulltime on VBdocman - new features, fixes, technical support…you name it. I'm proud to say that thousands of registered users regularly employ VBdocman to generate their technical documentation and, more importantly, keep the documentation current.

Palo: [ordinary 'thank you' stuff here]

Peter: [ordinary 'you are welcome' stuff here]

Bratislava, Slovakia, Wednesday, October 08, 2003

Click here to learn more about VBdocman.