[drupal-docs] Regarding the drupal help documentation

[Dan Robinson]

>
>Dan Robinson wrote:
>
> > ok - agreed that it needs to be formatted - it seems that others
> > disagree about the length.
> >
>
>LOL
>
>Length is not the only--nor the best--measure of the rhetorical
>effectiveness of a document. 
>
of course - I hope that it wasn't taken that way. Last night I put my 
head down to do a bit of writting and when I was finished I had a 
replacement approx 3x longer than that which it replaced.  So when 
someone asks for a short essay as opposed to a novel then size does 
matter - that is what I was trying to establish - whether the length 
disqualified my piece from use in the help text - some said yes, one 
said no (so I'm losing the vote :) ).

>Structure, formatting, conciseness,
>attention to use of appropriate language, awareness of the particular
>tasks that users want to accomplish--these all affect the usability of
>the document, and a 500 page manual that is properly put together may be
>more effective than a 1000 word quick start guide.
>
>To borrow from what Dries quoted, I think that Krug is off his rocker
>when he says "Instructions must die." Otherwise, the "X for Dummies"
>would not have exploded on the popular documentation market (people do
>find those very useful). Tutorial style howto's have their uses;
>reference guides do too. Each for different rhetorical situations.
>
>However the next point of Krug's has some validity
>
>"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."
>
>True. People aren't going to wade through a lot of instructions just to
>learn conceptually about a module on Drupal. They might want a brief
>explantation, though. Then once they are ready to perform a particular
>task, they'll want the howto.
>
>So one good organizational approach for a longer text like the block
>help you are putting together is something like
>
>1) Introductory paragraph describing the thing (for those that want the
>general description)
>2) Section(s) dealing with more detailed conceptual things (for those
>that have read or want to skip the introduction and want more detail)
>3) Howto's for doing the harder tasks (for those that have muddled
>through trying to do it on their own and are ready for the detailed
>instructions).
>  
>
This is excellent - and seems to be a very good style guide for the 
longer documentation that is being prepared - this is exactly the kind 
of feedback I was looking for.  However what should a parrallel set of 
guidelines look like for the admin/help screens?

>Charlie
>  
>