[drupal-docs] Admin help longs to be read by skilled Drupal user

[Kieran Lal]

On May 28, 2005, at 7:41 AM, Anisa wrote:

> Can we make the titles shorter?

Yes, shorter is better, except when less comprehensible.  As you can  
tell, I just plain ran out of clever things to say by the time I got  
to the S's.  I'll make your suggested changes and any one else's  
suggested changes for handbook titles.

>
> For example:
> blocks: sidebar content
> blog: a blog for every user

Blog was the most looked up word in 2004, I suspect that lot's of  
folks will read this as, blah: blah for every user.


> comment: allow comments on content (<- this sucks but is better than
> discussion boards for nodes ;p)
> Locale: multi-language support
> Node: all content
> Search: search your site

Should you use the word that you are trying to elaborate on.  I guess  
it's ok.

>
> There are a couple of others that stand out as needing to be a bit
> better.  Ie, Taxonomy, Path, *BOOK*.

Book got orphaned.  I'll see what I can do. I'll try and rewrite  
Taxonomy and Path.

>
> The statistics title is cute, but...

not as good as what you were going to suggest....

> Where was that wiki again?  ^.^;;

It died the death of being an inferior solution.

>   Maybe I don't have much right to
> complain because I didn't help much (it's a rare day I leave work  
> before
> 9 pm these days >.<  working 12 hour days at 23, where's the  
> justice in
> that? ;p),

Oh please, you are a slave driver. ("Can we write some documentation  
now!?")

> but there is a *lot* of unnecessarily technical language in
> there, and references to things the end user may not know, and for
> Drupal purposes, does not need to know.

Ok, tell me and I'll remove it or rewrite it.

> Drupal loads a little slow when I go to the edit page, I wonder why  
> that is.
>
> What to do with unresolved comment questions that are really support
> questions in disguise?

So one of the great things about being in charge or volunteering is  
you get to do stuff, like go through the handbook and delete  
comments.  Have fun!


> Path describes the permissions associated with the module, but other
> help texts do not.  Useful feature.
Yeah, I decided to not include permissions in the admin help for now  
because it was so redundant, although not obvious.  The exception is  
Node Privacy By Role which requires not just permissions but is  
disabled unless explicitly enabled in it's administration interface  
which is not the norm.

> Somehow I think this could all be made more readable...

Absolutely.  Ideally this would the first of many iterations, just  
like Drupal itself.

Cheers,
Kieran

>
> Anisa.
> sleepy.
>
> Kieran Lal wrote:
>
>
>> Howdy, 203 of you completed the Drupal documentation survey and told
>> us that the number one thing you wanted was module documentation.
>>
>> The goal of this admin help documentation is:
>> 1) Provide documentation for Drupal modules.
>> 2) Improve the usability of the admin help.
>> 3) Improve the documentation teams ability to work with admin help by
>> single sourcing it from the documentation handbook.
>>
>> Here is the documentation for Drupal core:http://drupal.org/handbook/
>> modules
>> Here is the documentation for some of Drupal contributions: http://
>> drupal.org/handbook/modules/contributions
>>
>> The handbook module pages start with executive summaries that are
>> also admin help.  Pretty clever, don't you think.  The handbooks are
>> currently under development, stay tuned for more improvements.  It
>> would be greatly appreciated if knowledgeable Drupal users could read
>> some of them and report back on where they are wrong.
>>
>> If you need a site to confirm this documentation, create an account
>> on: http://demo.civicspacelabs.org/home and send me a link to your
>> profile.  I'll make sure you get the access you need to confirm the
>> documentation is accurate.
>>
>> Thanks for you help,
>> Kieran
>>
>>
>>
>>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>