Sandcastle and HTML Help Builder.
I'm currently creating, what I hope to be, a very professional WebControl, and therefore with all the bells and whistles it can have, and this includes end user documentation.
Writing technical documentation after any software is build is a royal pain in the... well, you know where.
Anyway, I usually write components documentation using the Visual Studio built-in XML comments, which permits me to write the docs as I work in the means and bits of the software.
So far so good, but when I needed to create the actual help files, I got stuck.
Then in order to produce the help files I shop around for a nice documentation automata.
My first thought was the West Wind HTML Help Builder which I used when I worked on a small company some years ago. Back then it provided me with a very nice experience creating help files.
However, it was not the winner because it works by importing and exporting the XML comments to its proprietary format, and when importing the XML comments back into the code it messes up with them.
One thing must be said about the West Wind company, though, it has one of the best relation with the costumer I've ever seen in any software company.
When I wrote complaining about the issues I was having with their products, the Developer Manager himself wrote me back, in a matter of hours and reported every single issue I had with, either a 'thank you for the feedback it will be taken in consideration for a next release' or a 'oops, my bad, that was not supposed to happen', and not with some automated anonymous reply. If I ever have a software company, I'll make sure that my costumers will be treated the same manner.
I got side tracked... Let me get back to the business.
My second attempt was with NDoc, an open source help builder, that interprets the XML comments and render them in a help file.
It was nice and easy but the main developer kill the project after some personal problems, as reported here. I understand his motivations, and fully support it.
And it was reading the note about the death of NDoc, that I learned about Sandcastle.
Sandcastle is package of command line utilities to create help files from the XML comments, completely automated and customizable.
Command line utilities are good, but if you throw in some GUI makes them even better, and that's what Eric Woodruff did. He created the Sandcastle Help File Builder, or SHFB for short.
It really improved my day, and made my help files to be created simply at the push of a button.
Writing technical documentation after any software is build is a royal pain in the... well, you know where.
Anyway, I usually write components documentation using the Visual Studio built-in XML comments, which permits me to write the docs as I work in the means and bits of the software.
So far so good, but when I needed to create the actual help files, I got stuck.
Then in order to produce the help files I shop around for a nice documentation automata.
My first thought was the West Wind HTML Help Builder which I used when I worked on a small company some years ago. Back then it provided me with a very nice experience creating help files.
However, it was not the winner because it works by importing and exporting the XML comments to its proprietary format, and when importing the XML comments back into the code it messes up with them.
One thing must be said about the West Wind company, though, it has one of the best relation with the costumer I've ever seen in any software company.
When I wrote complaining about the issues I was having with their products, the Developer Manager himself wrote me back, in a matter of hours and reported every single issue I had with, either a 'thank you for the feedback it will be taken in consideration for a next release' or a 'oops, my bad, that was not supposed to happen', and not with some automated anonymous reply. If I ever have a software company, I'll make sure that my costumers will be treated the same manner.
I got side tracked... Let me get back to the business.
My second attempt was with NDoc, an open source help builder, that interprets the XML comments and render them in a help file.
It was nice and easy but the main developer kill the project after some personal problems, as reported here. I understand his motivations, and fully support it.
And it was reading the note about the death of NDoc, that I learned about Sandcastle.
Sandcastle is package of command line utilities to create help files from the XML comments, completely automated and customizable.
Command line utilities are good, but if you throw in some GUI makes them even better, and that's what Eric Woodruff did. He created the Sandcastle Help File Builder, or SHFB for short.
It really improved my day, and made my help files to be created simply at the push of a button.
posted by Paulo Santos
|
10/08/2007 05:37:00 PM
0 Comments:
Post a Comment