[drupal-docs] Regarding the drupal help documentation

[Charlie Lowe]

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

Charlie