2

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?

Improve this question

6 Answers 6

Reset to default
4

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
Improve this answer
3
  • 100 times yes. It's not earthshattering if I need to pull the server location up from my laptop in order to read the PDF or DOCX - but CHM really needs to go play in traffic.
    – Kara Marfia
    Jul 9, 2009 at 14:59
  • I went with SHFB - shfb.codeplex.com. It produces CHM files which I then convert to HTML.
    – Cheeso
    Jul 12, 2009 at 5:23
  • That looks like a pretty neat tool. Plain ol' HTML makes me much happer than CHM, as it will for a lot of other "IT people". Tell your developer friends to come here and ask us questions like yours during product / documentation development. We will reciprocate by liking their products and telling our sysadmin friends... >smile<
    – Evan Anderson
    Jul 12, 2009 at 6:17
0

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...

Improve this answer
3
  • I've got this vision in my head of the bits blinking out on an LED... "01000101 01010110 01000001 01001110 00100000 01010010 01001111 01000011 01001011 01010011..." Okay.. got it.
    – Evan Anderson
    Jul 9, 2009 at 15:16
  • LOL... I said ASCII... not binary. That being said... I do have a Morse code application on my phone... not that I actually know Morse code or anything. HA HA HA
    – KPWINC
    Jul 9, 2009 at 17:46
  • I think it was Neal Stephenson's "Cryptonomicon" where one of the characters sits around writing code, paranoid to display it on his screen for fear of TEMPEST attacks, so he blinks a keyboard LED with Morse code... yeah. I'm seeing something like that, but with binary and the blue "ident" LED on a Dell server... >smile< 01000011 01100001 01101110 00100000 01111001 01101111 01110101 00100000 01110010 01100101 01100001 01100100 00100000 01110100 01101000 01101001 01110011 00101100 00100000 01110100 01101000 01101111 01110101 01100111 01101000 01110100 00111111
    – Evan Anderson
    Jul 10, 2009 at 12:20
0

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.

Improve this answer
0

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

Improve this answer
0

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). /

Improve this answer
0

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.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .