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

[Kieran Lal]

On May 27, 2005, at 4:27 AM, Kobus Myburgh wrote:

> Hi, I have been looking around at the handbook and the websort, and  
> some things are bothering me:
>
> 1. In the contributed modules page, take, for example, the  
> buddylist module. It says "you can: allow users to view profiles  
> in  access permissions", which links to Drupal's access  
> permissions. Most people don't have access to those, for obvious  
> reasons, but it still leaves a "bad taste". Either remove the  
> links, or point the link to generic help for the topic instead of  
> trying to go to the page in question.

This is an ongoing debate.  I appreciate  your feedback in it.   Many  
of the handbook pages actually link to internal Drupal administration  
pages.  You are right this is bad form.  However, it is useful to  
have Administer >>  modulename >> configure so that users can read  
along.   I refer to that as bread crumbs.   The question is should  
bread crumbs be an actual link.   We are working to come up with a  
solution for three cases.
1) The documentation is exported from the handbook to admin help.  We  
need the links to actually work, and we will probably remove the  
bread crumbs, but keep the link.
2) The documentation is exported as a handbook and hosted live as a  
book on a users site.  In this case you want the links to work.
3) The documentation is hosted on Drupal.org and you want to  
highlight the bread crumbs, but you don't necessarily want the links  
to work.

Charlie has been encouraging me to come up with single solution first  
and implement it, but I assured him that I am having to review all 60  
handbook pages so frequently that I'll quickly be able to implement a  
standard as we discover it.  In the mean time Djun and I will be  
talking on the phone this morning to see if we can automate a way for  
3) to become 1) and 2).

>
> 2. As far as the websort is concerned, there are so many categories  
> on the left-hand side that doesn't fit ANYWHERE in the second  
> column, as far as I can make them fit. Something like "Block  
> tutorial" where does that go? My gut feeling says "developing for  
> Drupal" (eish? - South African word for "really!?"), but depending  
> on the context of what Block tutorial contains, that should be in a  
> section "Help" or something. What about "Configuration and  
> customization" as you do customize blocks as well... Maybe I am  
> looking to literally at this?

Exactly!   That is why there is a column on the right called Don't  
know/Don't understand.   The intention of the experiment is to help  
us discover how the handbooks could be organized for the most users  
effectively.  The results of the clustering in the Dendogram will  
tell us if there are too many titles in the Don't know/Don't  
understand category.   We would be sure to rename those document  
titles if they were in that category.

The truth is you are absolutely right, many of the potential  
documents could go in many places.   When we aggregate all the  
results and look at the clustering then we will have an idea where  
most people would put the documents.   That will make the document  
more usable because most people will find it, where they would expect  
it.   We might decide to hyperlink the document in two places, or we  
might decide that the majority should rule.

If you were interested in doing more detailed analysis I could make  
the raw data available.

Kieran

>
> Regards,
>
> Kobus
>
>
>
>>>> kieran at civicspacelabs.org 5/27/2005 9:18:46 AM >>>
>>>>
> 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 ]
>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>