Creating helpfile in HTML

Question

I am facing the fun task of creating a Help File for a large project. I have discarded CHM files due to the constraints and are now looking into HTML based files but I am still undecided on the format....

There are 3 areas I'm focusing on:

Reusability of sections (many pages can refer to one text) Since some sections will be used more than once in the helpfile, i need to create a master section and then link to the master sections in each subsection. This so I avoid having to change the caption multiple places when doing edits.

Searchfunctionality I would like to be able to search free text in the file.

Printability. The user can select to print sections or wholde document.

I was first leaning to the wiki approach having plugins to export the wiki into static pages for distribution, but I have not found that solution...

Any suggestions from you guys in this matter? Am i making helpfiles to complicated?

Thanks in advance!

Answer 1

Reusability

I see two approaches. You can either create individual pages for the sections that you want to reuse, and then simply link to them wherever appropriate. This is trivial in HTML.

You can alternatively create a snippet or fragment of HTML with the information for that section, and then use Server-Side Includes (or a similar technology) to include it inline wherever it's needed. This way the content will appear to have been written on every individual page, but when you need to make an edit it's still only in one place.

Search

If the site is public, let Google index it, and just offer a Google search box. You're not likely to get better results than that.

Printability

A "print stylesheet" in CSS is easy to put together, and can eliminate all the graphical elements that make the site attractive on the web, preserving all the content for use on paper.

Printing the whole document at once would require some small bit of programming to combine all the contents together into a single page for the purpose of printing. Personally, I'd prefer to even offer that service, to discourage people from wasting the paper.

Of course, we can offer all manner of insight into how to achieve any of these things, but since it sounds like you're after general advice at the moment, that's mine.

Answer 2

I believe wikis are perfect for documentation, especially when more than one person is (or will be) involved in the project. Linking between wiki pages or namespaces is easily achieved. Renaming a page will change all hyperlinks in other documents. I would avoid duplication of content wherever possible though, if that's what you were suggesting.

I use DokuWiki which supports page exporting. You can dump your entire wiki into plain text, XHTML or XHTML body (for putting inside your own template, or to append to a single file for printing, etc).

Hope that helps!