[drupal-docs] Regarding the drupal help documentation

[Dan Robinson]

>> http://dev.bryght.com/t/wiki/BlockHelp
>>
>> I didn't understand how to make the text any less complete than it is
>> and still have it be useful.  I got a perfectly reasonable response from
>> Kieran this morning - to the effect that it is too long - not
>> surprising, here's my (longwinded) response:
>
>
> I agree with Kieran that this is long-winded.  Here are some suggestions:

actually I referred to my post as "long-winded"  ;)

>
> 1. Remove the GUI descriptions.
>
>     Example: "Each Block listing includes a Block Name, an "enabled" 
> check box, a "weight", radio buttons for placing the Block in the left 
> or right sidebar, and a link that allows for additional configuration. 
> (If you have enabled the "Throttle" module there will also be a check 
> box that will allow the Block to be "throttled". See th Throttle 
> documentation for more information on this)."

ok - so this stuff should just be an overview of what the admin page 
does I guess.

>
> 2. You are repeating yourself:

ok - so you want terse.  I "get" that - however a lot of 
non-technical/non-programmers are going to be very confused - we 
(people) generally absorb things through a certain amount of repition - 
in the example below one explanation is what the specific widget does - 
the other is a general discussion of what this thing does - but this is 
consistent with your comment above "lose the GUI descriptions".

>
>    Example: first you write
>       "Weight" is a number from -10 to 10. Blocks assigned the 
> smallest "Weight"
>       will "rise" to the top of the column, those with larger numbers 
> will "sink" to the
>       bottom."
>   only to start again a couple paragraphs later:
>       "The block management screen lets you specify the vertical 
> sort-order of the
>       blocks within a sidebar. You dothis by assigning a weight to 
> each block.
>       Lighter blocks (smaller weight) "float up" towards the top of 
> the sidebar.
>      Heavier ones "sink down" towards the bottom of it."
>
>    The same is true for the sidebar explanation.
>
> 3. Remove useless information or obvious instructions.

no useless information?  hmmmm.... but I like useless information and 
obvious instructions ;).  I think that I'm trying to assume as little as 
possible from the user and go for completeness.  You seem to be asking 
for something else.

>
>     Example:
>        "Weight is a number from -10 to 10."
>        "To create a new custom block you enter a "Block title", choose 
> your preferred input format, enter in the text that will appear in the 
> Block (or php code that will execute when the Block is displayed) and 
> then add a brief "description" of the Block. Once this is done and 
> saved the new custom Block will appear in the admin/block screen."
>        "Clicking on the "Configure" link takes you to the Block 
> "Configuration" page."
>
>