Suggestions on Documentation Style

This page contains my suggestions on documentation style. I will try to demonstrate my suggestions by writing a document that justifies them. I'm an advocate of learning by example. As Mark Twain said, "Few things are harder to put up with than the annoyance of a good example" (Samuel Langhornne Clemens (1835-1910)).

...

Headings should definetly be used. This sections tries to justify why.

First rule: However, don't use "h1" at the top of each page. The page title serves as the "top level header" already, so there is no need to duplicate that information again. Also, when the docs end up the website, SiteMesh will place a top level "h1" element using the page title.

...