DEV Community

Discussion on: What are some examples of great documentation?

Collapse
 
oscherler profile image
Olivier “Ölbaum” Scherler

Negative examples:

Bootstrap v3: You can't navigate between pages without scrolling all the way back up, elements are spread randomly between CSS and Conponents. A long and useless icon reference takes all the space at the very beginning of the Components page.

PHP: there's no per-version docs, you have to solve a logic puzzle spread between multiple aside boxes to know what you can do with a function on a given PHP version. Navigation is aweful.

Doctrine: everything is there, but it's impossible to find without a trip through Google. For a long time the API reference wasn't reachable from the documentation pages.

Terrific JS: everything is spread randomly: when you need to know how to do something, you cannot find it because it's not in its logical place. If you don't know something is possible, you will never find out. The only ways to use these docs are a) to read them all in sequence, in one sitting, and learn everything by heart'or b) to read everything every time you need to look up something.