Writing Web Help Pages

[OtagoHarbour]

I was wondering if someone could tell me the best way to write help pages that are linked to from one's web pages. (Like the Help tab at the top of this page.) Would one simply use html? Are there specific tools (like doxygen for C++)? It seems that W3Schools uses PHP. Is that the best approach?Any thoughts would be greatly appreciated,Peter.

[thescientist]

I think the W3Schools website uses ASP. The forum uses PHP.It would seem that if you can and know how to organize the content via a database, then having a server side implementation update a HTML template page might be an easily maintainable option. Otherwise, you could just maintain different static HTML pages.

[jeffman]

If it doesn't need to be searchable, static pages would be useful, or perhaps a template document that includes an appropriate content file, or inserts text from a database, depending on the request.If it does need to be searchable, static pages or include files would work, but would be slower than text stored in a database, and less scalable.A lot of sites just have one static help document that you navigate with jump tags. How useful that is depends on the amount of help information you want to provide. It's also not especially scalable. If the thing needs to keep growing over time, it'll be hard to maintain. A variation on this theme might use database to "assemble" the help document w/ jump tags on the fly. The best help files of this type have jump tags to each section, and each section has a jump tag to return you to the index at the top of the page. Some even have a little search box attached to each section. A big limitation to this sort of thing is that you are stuck with the entire index or jumping to a single section.I find the most useful help systems give you a search box and return a set of links with relevant text for each one, listed in order of relevance. You can determine relevance by counting the number of times search term is matched in a given file or DB record.

[OtagoHarbour]

I think the W3Schools website uses ASP. The forum uses PHP.It would seem that if you can and know how to organize the content via a database, then having a server side implementation update a HTML template page might be an easily maintainable option. Otherwise, you could just maintain different static HTML pages.

Thank you for your hep.

[OtagoHarbour]

If it doesn't need to be searchable, static pages would be useful, or perhaps a template document that includes an appropriate content file, or inserts text from a database, depending on the request.If it does need to be searchable, static pages or include files would work, but would be slower than text stored in a database, and less scalable.A lot of sites just have one static help document that you navigate with jump tags. How useful that is depends on the amount of help information you want to provide. It's also not especially scalable. If the thing needs to keep growing over time, it'll be hard to maintain. A variation on this theme might use database to "assemble" the help document w/ jump tags on the fly. The best help files of this type have jump tags to each section, and each section has a jump tag to return you to the index at the top of the page. Some even have a little search box attached to each section. A big limitation to this sort of thing is that you are stuck with the entire index or jumping to a single section.I find the most useful help systems give you a search box and return a set of links with relevant text for each one, listed in order of relevance. You can determine relevance by counting the number of times search term is matched in a given file or DB record.

Thank you for your help. Do you think that there would be a problem with setting up a static document with jump tags, in the short term, and developing text stored in a database in the long term?Thanks again,Peter.

[jeffman]

A problem? No. Setting up a database won't be much more than copy/paste from the existing document, and even that could be automated if the static document is well organized.