[documentation] A suggestion to improve drupal.org handbooks

[Ram Dak]

Thanks, Kieran. I will answer in detail later but I can do the screenshots if you could give me the specs.
  
  Ramdak
  

Kieran Lal <kieran at civicspacelabs.org> wrote:  
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/
 

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/


			
---------------------------------
Yahoo! Photos
 Got holiday prints? See all the ways to get quality prints in your hands ASAP.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20060119/ee2ec619/attachment.htm