[drupal-docs] Regarding the drupal help documentation

[Dries Buytaert]

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

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/