Best software for writing HTML-based user manuals [closed]

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.

Feeder

Is there any reason why you don't want to use something like mediawiki? Unlike (X)HTML, MediaWiki has a light-weight syntax (though I have to say I prefer markdown syntax), and you don't need professional-grade documentation, and I've seen several open source software used it for their documentation. And you definitely have a PHP-enabled server, since the app itself is written in PHP. You can simply disable anonymous editing and account creation if you don't want just anyone to be able to edit the doc. – Presser

Answer 1

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.

Swain

This is basically exactly what I was looking for :) Thanks! – Feeder

Answer 2

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 :)

Solomonsolon

The Sphinx link dose not work anymore. – Premillennial

Answer 3

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.

Mcmillin

I like that OO is supporting a format like DocBooks but it seems like the support is in its infancy. Thanks for the suggestion, though. – Feeder

Answer 4

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.

Nunhood

unless you're typesetting for a printed book, you don't need to care if the page is 1 pixel off or is rendered in different font in some other OS. For this reason, I'd say HTML is more platform agnostic than PDF. – Presser

@Lie Ryan: HTML doesn't have support for embedding fonts, and CSS has wild variations of interpretation between different browsers (especially older ones). – Nunhood

but you don't need (and shouldn't need) to care about what font or color the text is rendered in. Basically, you just need the text to be readable and you can show images and embed videos/sound and other multimedias (flash, java applet, etc). – Presser

You can embed fonts into your website via Webfonts. See en.wikipedia.org/wiki/Web_typography and code.google.com/apis/webfonts – Falange

@bluebrother: Quite interesting about the CSS font-downloading support, I hadn't heard about that. Anyway, I agree that the font shouldn't matter as much as the clarity. The ideal solution would be something like the Sphinx answer above that can publish to multiple formats, including both HTML and PDF. – Nunhood