[drupal-docs] Regarding the drupal help documentation

[Dan Robinson]

>
> On 10 May 2005, at 18:34, Dan Robinson wrote:
>
>> 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:
>
>
> My usability book "Don't make me think", written by usability expert 
> Steve Krug has this to say about writing for the web:
>
>    "Instructions must die.  The main thing you need to know about 
> instructions is that no one is going to read them -- at least not 
> until after repeated attempts at /muddling through/ have failed.  And 
> even then, if the instructions are wordy, the odds of users finding 
> the information they need is pretty low.  Your objective should always 
> be to eliminate instructions entirely by making everything 
> self-explanatory, or as close to it as possible.  When instructions 
> are necessary, cut them back to a bare minimum."

ok - so what are we saying here? That the code as is is self-explanatory 
and indeed needs no documentation?  I have looked through everything I 
have been pointed at and still have yet to see a clear description of 
who the reader is and what the goals and objectives of this exercise 
is.  Here is the original documentation from admin/help/block -

===============================

Blocks are the boxes visible in the sidebar(s) of your web site. These 
are usually generated automatically by modules (e.g. recent forum 
topics), but you can also create your own blocks.

The sidebar each block appears in depends on both which theme you are 
using (some are left-only, some right, some both), and on the settings 
in block management.

The block management screen lets you specify the vertical sort-order of 
the blocks within a sidebar. You do this 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.

A block's visibility depends on:

    * Its enabled checkbox. Disabled blocks are never shown.
    * Its throttle checkbox. Throttled blocks are hidden during high
      server loads.
    * Its path options. Blocks can be configured to only show/hide on
      certain pages
    * . User settings. You can choose to let your users decide whether
      to show/hide certain blocks.
    * Its function. Dynamic blocks (such as those defined by modules)
      may be empty on certain pages and will not be shown.


      Administrator defined blocks

An administrator defined block contains content supplied by you (as 
opposed to being generated automatically by a module). Each 
admin-defined block consists of a title, a description, and a body which 
can be as long as you wish. The Drupal engine will render the content of 
the block.

=============================

So maybe someone could tell me what is wrong with this help text?  
Anyway - I am genuinely trying to help (sorry this is getting so 
difficult) but I don't want to march off and produce a bunch of 
documentation that won't get used.  I would much rather be writing doco 
than these emails.  (does anyone think what I wrote would be useful in 
the documentation proper? - If so perhaps the answer to this riddle is 
that Dan should be writing the longer text and leave the short text to 
the professionals?).

Collegially,

Dan

>
> He quotes E. B. White's seventheenth rule in The Element of Style:
>
>   "Vigorous writing is concise.  A sentence should contain no 
> unnecessary words, a paragraph no unnecessary sentences, for the same 
> reason that a drawing should have no unnecessary lines and a machine 
> no unnecessary parts."
>
> Krug's third law of usability reads:
>
>   "Get rid of half the words on each page, then get rid of half of 
> what's left."
>
> -- 
> Dries Buytaert  ::  http://www.buytaert.net/
>
>