HTML Documentation Layout and Navigation
Documentation for versions up to version 4.50 used a framed page layout which had table of contents or index information in a separate pane for easy navigation. However frames have problems, and this was looking dated and could be better optomised for usability both for novices and experts.
Version 4.6 generated HTML documentation using docbook. This had some advantages, but signficantly poorer navigation (IMHO).
I would like to collect examples of documentation that people think works well - is easy to navigate, well laid out etc. Please add links to examples of good documentation (that you believe have lessons that could be applied to the exim docs) to the list below. Put a short comment showing what aspect(s) are really good.
PHP Manual - short sections, good navigation via stacked menu on left.
MySQL Manual - Similar to PHP - expanding/contracting contents table on left, users can add comments to any page (Blog-style rather than wiki-style) recommended by PeterBowyer
FreeBSD Handbook - I've always found the FreeBSD handbook enjoyable to read. Can't quite put my finger on why though. BobJohannessen
Documentation Comments
Some of the examples above have documentation which can be commented on. This is an interesting thought, but has one major disadvantage - the (tarball) distributed version of the documentation cannot have these comments. I'd like to work on getting static versions working well and then add commenting in a way that allows local copies to be distributed rather than requiring more than a really basic webserver to use with the distributed docs.
Maybe a hybrid approach - the offline version is the online version without the comments, but with URLs to the online commented versions of the same page. PeterBowyer