Best software for writing HTML-based user manuals

Jazzepi picture Jazzepi · Sep 27, 2010 · Viewed 12.2k times · Source

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

Shaun Mason picture Shaun Mason · Sep 28, 2010

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.