So I've seen a variety of documentation online for various software technologies I've used. Four things that appear to be common to all the good ones are 1) an outline or tree depiction showing the documentation structure, 2) A search capability, 3) User comments in the documentation, and 4) An active user forum where people can ask for help.
Examples
PHP's documentation is cool because you can just type in http://php.net/cmdName and get to the page of interest. This is super helpful. More importantly, I feel that the docs there are particularly clear and well-written for the most part with lots of illustrative examples. The user comments are also useful sometimes. As far as I know there is no single native PHP forum. This one is all I need 🙂
MySQL's documentation is pretty cool because generally when you search 'mysql something' on google you get the mysql documentation pages. Like PHP's docs, this has a TOC/tree structure only with some extra Javascript to show/hide sections. As with php.net, delving into any particular section results in a narrowed navigation pane showing subsections and sibling sections. Documentation is neatly grouped by version. The MySQL forums are not very active. It's often hard to get an answer.
Adobe's Flash Documentation has the same tree and search features but the tree takes forever to load, the search is slow and takes you to pages which look similar to the home/index page but are apparently entirely different sections with a different tree. Clicking on particular nodes in the tree will surprise you by opening an entirely new window. Most importantly, the documentation for the most part is imprecise, vague, or poorly written. Their user support forums show similar dysfunction. There are a few users who are very helpful, a great many who are confused and useless, and the forum implementation is exceedingly poor.
Does anyone have opinions about what is required, what is gravy, and what should never be done? Perhaps examples of truly helpful documentation? Any feedback would be much appreciated.
