This is not a rant.
Drupal rocks.
However, in order to shed the stigma of being targeted only at super-geeks, everybody agrees that the documentation needs some serious upgrading.
I have what I think is a simple suggestion that may go a long way towards removing the stigma: when any code snippet is shown, or any other similar action step, there should be two cross-references in the description immediately after (or before) the item in question:
1) pre-requisites
2) insert location
I could argue that the first should be a link, and that after a suitable set of links is established, inserting such a link would become trivial, but until a satisfactory set of links is established, an inline list would satisfy.
As an example, here is a link to a description of how to add a custom element from the "Forms API Quickstart Guide", found at:
http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/...
Begin Quote:
For example, here's how to go about constructing a textfield form element:
$form['foo'] = array(
'#type' => 'textfield',
'#title' => t('bar'),
'#default_value' => $object['foo'],
'#size' => 60,
'#maxlength' => 64,
'#description' => t('baz'),
);
End Quote
I defy anybody who is not intimately familiar with Drupal to understand where this snippet is to be placed. Further, on the page, there is nowhere that indicates the version of Drupal that the Forms API being referenced applies to. Those who follow the versioning of Drupal may know that the Forms API is not available to versions of Drupal prior to a certain specific version. Those that don't may be confused. Why should they be confused when it is so easy to ensure that their confusion is eliminated?