The worst time to read software documentation is when you're trying to fix something that is broken and you have no idea why. I'd say it's like shopping when you're hungry, but it's actually the opposite. When stuff breaks for no apparent reason and you're on edge it's easy to notice every little issue with the docs, and you instantly form a very strong opinion on documentation.

The good news is that as a Drupal developer, you have tons of awesome documentation just a click away on api.drupal.org or drupal.org/documentation/develop and contributed module documentation is better than ever. Even though almost everything you could ever want to know about Drupal internals is available on api.drupal.org (even the source code!) sometimes you need to combine that with contributed docs, or dig in a little deeper.

That's exactly what I had to do while working on the first few chapters of Model Your Data with Drupal. Hooks like hook_entity_info() are well documented on api.drupal.org, but the Entity API module adds it's own options to the mix. Entity API has great docs on it's options as well, but there isn't a lot out there that thoroughly documents them together, or the interaction of their options.

Read more