[documentation] A suggestion to improve drupal.org handbooks

[Kieran Lal]

On Jan 19, 2006, at 12:29 AM, Ram Dak wrote:

> I have a few ideas for improving the handbook documentation and  
> would like to volunteer for implementing them if the people on this  
> list think they will help.
>
> These ideas are based on the tremendous difficulties I have had as  
> a non-geek in understanding what a drupal core or contributed  
> module does. The only way is to test each one out and this can be  
> really time consuming when testing multiple modules.

I realize that it's probably not perfect but most of what you have  
asked for is here:

http://drupal.org/handbook/modules
http://drupal.org/handbook/config/contribmodules

Give me a list of modules that are not included that you are willing  
to document and I'll help you write pages for them.

As you probably know these pages have been included the CivicSpace  
distribution since July, 05.
>
> Current problems that newbies (and, I suspect, even others) have in  
> understanding modules:
>
> 1.) Whether a module is dependent on another
Dependency will be outlined in administration help handbook pages as  
well as administer >> help >> modulenames in your Drupal  
installation.   There is some forth coming work on dependency.

> 2.) Whether an sql table should be added to make it work

Check the readme in the tar ball you download.  It could be outlined  
in the project page.   I am not sure that moving it to the project  
page is going to make much difference since you have to open the  
package of code.

> 3.) No idea about the different tables added by a module's sql file

Well, you could look at the MySQL file.  I suppose this could be  
outlined on the project page.

> 4.) No idea about the permissions implemented by a module.

http://drupal.org/handbook/modules as this page indicates permissions  
are determined by administration >> access control.

> 5.) No idea of what stuff a module adds to the navigation menu and UI.

OK, this is interesting.  I have tried to include links to  
configuring module blocks if the module has specific blocks.  I can  
understand that modules add menu items to the navigation menu block.   
Can you give some other ideas of how modules modify the UI other than  
blocks and menu's.  I think the banner module and front page would  
have UI changes.

> 6.) Whether the module adds customs blocks that can then be enabled  
> and configured.
>
The handbook pages should have this in the You can: section.

> There may al so be other aspects that I have overlooked.
>
> I believe that documenting these would go a long way in helping  
> people get up to speed on drupal very quickly. For example, until I  
> got into the habit of visiting administer>>access  
> control>>permissions>>module name>>permissions, I spent hours  
> wondering why a module was not working. I bet many face the same  
> problem.
>
I have debated whether to add a link to permissions for each handbook  
page and decided that it ultimately was fundamental for every module  
and repeating it everywhere didn't make sense.  I do believe it's  
featured prominently on the administer >> modules page.

> If this sounds useful, I am willing to do this work for 4.6 (as  
> that has the largest user base at the moment), starting with each  
> core module and moving on to the contribs.
>
Ok well there's already been hundreds of hours of work on this.  If  
you want to expand the pool of administration help pages for  
contributed modules that would be great.  We are currently trying to  
make sure that the 80 modules here http://drupal.org/handbook/modules  
are linked to their project pages and that their modules project pages 
(or CVS) are linked back to the documentation.

> I also feel that if the handbook would allow screenshots, it would  
> make for great documentation. As they say, a picture is worth a  
> thousand words and all that.
>
Absolutely agree.  We are looking for someone to take screen shots of  
administration menu's.

It's best to start with a single steady contribution, so pick one and  
we can work together to make some of your contributions possible.

> Thanks,
> Ramdak
>
> Yahoo! Photos – Showcase holiday pictures in hardcover
> Photo Books. You design it and we’ll bind it!
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20060119/fa947d67/attachment.htm