Best software for writing HTML-based user manuals

Question

I'm working on a project where I need to generate end-user documentation for a piece of software. At some point in next year, the piece of software that I am writing this documentation will be retired. Therefore, I do not wish to spend a great deal of time on a professional-grade manual. This is something that graduate students at a college, and a few in house professionals, will be seeing. Though if it's good and useful enough, I might feed it back into the opensource community as free documentation.

I was thinking that an HTML manual would be a good fit. The software is written in PHP, so whomever is using it will have a web browser open and ready to go. This also leads to the possibility of me, or someone else, integrating the manual's pages into the software itself.

I am not interested in making/using a wiki for this piece of software. What I am really looking for is a piece of software where I can write like a normal document and generate simple HTML. I know that there are pieces of software like Dreamweaver and Frontpage but I was particularly interested in something designed to make the process of documentation creation easier (where the process of taking screen-caps and videos is integrated along with simple image/video editing).

If you think that another approach (other than HTML docs) might be better, I'd love to hear it. If you have another approach, and you think you know a good software solution for achieving that, let me know.

My main desires for the approach and the software to achieve it are

• Simplicity in deployment (HTML pages require no special setup. A help directory can simply be deployed with all the manual pages in it)
• No special software required to utilize (HTML can be read by everyone that has a web browser)
• Ease of use for me writing the documentation / small learning curve (I don't want to spend a lot of time learning a complicated piece of software to work on a relatively small project)
• Ability to combine text, videos, and images into single documents (HTML pages obviously support displaying all of these together)

Thanks!

@Lie Ryan : "MediaWiki stores all the text and data (content pages, user details, system messages, etc.) in a database..." which is what I want to avoid. I think that wikis are great and useful, but I'm just interested in providing static data with very low overhead.

Answer 1

Write the manual in XML, use something like docbook. This will let you do whatever you need to with the content and then generate the presentation in it's own way.

There's a lot of tutorials on docbook to HTML tools out there.

Edit: I forgot to mention that OO can save in docbook.

Answer 2

I would suggest just writing it in OpenOffice and publishing to PDF. PDF, perhaps even more than HTML, is platform-agnostic and appears nearly identical across multiple clients and operating systems. If you really want video you can link to an external website such as Youtube or what-have-you from the PDF.

Answer 3

I guess this doesn't exactly meet all your requirements, but I'm a big fan of Sphinx. You write your documentation in ReST, and you can generate HTML and PDF versions quite easily. The HTML generation uses templates, so it's quite customizable. Also, there's the added benefit of having the plain text versions around (ReST is somewhat readable as-is) for those of us who like such things :)

Answer 4

Whenever I am required to write user manuals (meaning every time I finish a project), I like to use Markdown. Combined with minimal CSS, it is very easy to use.

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.