Home / server / Questions / 38326
Accepted
Cheeso
Asked: 2009-07-10 06:53:47 +0800 CST

How to deliver documentation for IT tools?

  • 772

I'd like to deliver an IT tool for use on Windows. The thing is an ISAPI Filter, and I want to describe installation, operations, and configuration.

Currently this is done in a text file, which is fairly complete, but I think it is not very usable. I think I have a good handle on what should be in the documentation. I'd like input on the How part. What's the best way to deliver documentation for Windows web server administrators?

.CHM? .PDF? .DOCX? .HTM ?

EDIT: I had a text file, but it was getting really long, and it had limited facility for linking, cross-referencing, indexing, and organization. LEt's see, a major section gets underlined with equals signs, a subsection gets underlined with dashes... etc etc. So I tried formatting it this way but in the end the .txt file just did not scale.

Update: I selected SHFB. Here's the output HTML help. What do you think? usable?

windows iis documentation

6 Answers

  1. Best Answer

    Here's my take:

    • ASCII text is great - I can read that anywhere
    • HTML is second-best - I can read that mostly anywhere, too
    • PDF is acceptable but somewhat annoying since I might need to refer to it on a server w/ no PDF reader installed
    • CHM is a pain because of the stupid HTML help control (thanks HTML Help control bugs / vunlerabilities!), and it's not a very friendly format to cut / paste from
    • DOCX is just plain annoying - I don't have "Office" installed on my servers and if I need to refer to the documentation there, I'm sure not going to load it
    • 4

  2. I've got to go with properly formatted ASCII text files. They can be read from the laptop, the server, windows, unix, linux, etc.

    I should not have to rely on a web browser, adobe reader, office, or any other program to read how to install something on my server. It should be simple and painless.

    Truth is... in a pinch... I could even read the text file from my cell phone if I had to.

    I'm sure anyone who's been stuck at a colo facility at 3am under less than desirable circumstances (ie. paged from the bar, no laptop, etc) would agree. ;-)

    Just my 2 cents...

    • 0

  3. You should check out asciidoc. I've made a few short things with it, and the output it pretty sharp (and customizable, of course). The plain text is very readable by design, and you can have it output docbook, HTML and PDF easily. Using any number of other converters you can transform it to other formats, too, such as CHM.

    Very versatile package, though, being a UNIX-centric package, I don't know how the Windows support is.

    • 0

  4. reStructuredText suits me well. It is easy to learn and use.

    • 0

  5. I know you already accepted an answer but I thought I would recommend sphinx. You write the doc in reStructuredText but can easily generate html that is searchable (tiny javascript). /

    • 0

  6. Here's another vote for plain text. If the documentation requires, or benefits from, illustrations of some sort HTML may be the best choice because a browser is more likely to be available than other reader applications.

    Please, never use DOCX or any other proprietary format unless there is an overwhelming reason to do so (and off-hand I can't think of a single one). Even if you want to create it as a Word file save it as DOC, not DOCX, as there is a larger range of software that can read the older format.

    • 0