[drupal-docs] Regarding the drupal help documentation

[Dries Buytaert]

On 10 May 2005, at 18:34, Dan Robinson wrote:
> 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:

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)."

2. You are repeating yourself:

    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.

     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."

--
Dries Buytaert  ::  http://www.buytaert.net/