[drupal-docs] Regarding the drupal help documentation

[Charlie Lowe]

My point is that this does work for the admin/help if structured correctly:

1) It provides the general information that Dries and Kieran believe is 
the only thing that people are looking (I disagree; this is only one 
audience) right up front. They find it right away.

2) It provides more detailed instructions for those that want it later 
on. I really don't agree with the idea that the best strategy is for 
users to go to drupal.org and dig through the handbook to find howto's 
on completing tasks. I think they are much more likely to take advantage 
of information available on their site. I tend to think more of what's 
going on here with that idea that the admin/help guide only needs a few 
paragraphs has to do more with the process of documentation 
implementation and maintenance: it has to be handcoded in to the modules 
leaving it up to coders to the work. So the problem here is with the 
practical implementation more so that an awareness of audience needs.

The other part is that the admin help is often geekified because it's 
only coder accessible. Whenever requests have gone out for 
revisions/updates to the documentation, it's typically been buried in 
php code, an easily readable medium for coders, but not for anyone 
else--thus, it tends to be written and revised by coders. So 500 words 
of geekfied text is better off replaced with a short description, but 
that doesn't mean it's the best solution.

3) If the community consensus is that the more detailed instructions 
aren't needed, then this top down--general, conceptual, 
instructional--approach means that the detailed instructions are merely 
left off the admin/help.

Charlie

Dan Robinson wrote:
>>
> 
> 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?