How to construct and deliver documentation for IT tools on Windows?

Question

How should I construct and deliver documentation for an IT tool on Windows? There's an additional constraint that I don't want to spend money on help authoring tools.

Here on SO, we talk about algorithms and optimizations, APIs and performance. But one of the deliverables from my dev efforts is documentation. What's the best way to build it, and in what form should I deliver it?

If I am delivering a set of .NET APIs, a .CHM is a reasonable mechanism for delivery. It's very easy to use SHFB to construct the help file as part of the build, and if it will be used mostly on Windows, a .CHM is very accessible. And converting the .CHM to .HTM makes the doc accessible even more broadly.

But I want to deliver doc for a ISAPI Filter which will be used not by developers per se, but by Windows web server administrators. I need to describe installation, operations, and configuration. I think the end users might often have developer as well as administrative skills, but in any case, for my purposes the documentation will cover administrative tasks and operational matters.

I know that SHFB allows me to include regular HTML files in the .CHM. If I already know SHFB, and if I don't want to spend money on a help-authoring tool, is this the best way to go? If not, what?

Answer 1

Try this asciidoc. It is not LaTeX, but produces nice PDF/CHM/HTML and you can teach non-programmer to write documentation for you, which is a nice bonus :)

Answer 2

Why not writing the documentation in open office and then export it in pdf?

Latex is the professional way, but it's not quickly accessible.

Answer 3

Texlipse is a Latex plugin for Eclipse. Both are free. Latext is used by many researchers to generate their papers and is even used for many text books. It's a free tool that could meet your needs.

Answer 4

In the end, I decided to use Sandcastle Help File Builder, the free tool available on http://shfb.codeplex.com. I already used sandcastle to build the reference doc for a different project, so I knew something about the tool. It produces CHM or .HxS files, suitable for use on Windows. I had never used SHFB to "design" a helpfule before, but it was pretty easy to understand how to do it. The results are very good.