[documentation] handbook reorg

Steven Peck speck at blkmtn.org
Thu Dec 29 00:04:24 UTC 2005


Greetings,
 
I've been pondering this for a while now and I have been following various threads and #drupal-support for people finding information in the handbook.  People get confused where to look for things.  I've never really had a good alternative to how it was setup.  The existing setup really just carried forward into 'seperate' books what was there structurally before.  I have pinged a few folks offline on this and talked with Dries and Charlie.  So now let's see see what everyone else thinks. 
 
I mean, I probably know it as well as anyone and I stumble across oddities more and more.  Dated content and such, though with the version tagging, it should help a lot. A lot of the existing content has been rewritten by a few folks and the rest doesn't look to be getting updated soon, so pruning (unpublishing) may be in order.  If it's stale, then let's make it go away, it may get some folks to get some new stuff in.
 
It would be nice to do it before 4.7 too.  I was thinking of suggesting .....
 
+About Drupal+
Stuff bout Drupal.  At this point this stays as is.  It needs a detailed going over, but not by me at this time.
 
+Installation / Configuration+
If it can be done just by installing modules and without modifiying anything or tweaked with php code, then it goes here (we don't need 'upgrading' as a top heading, merely a section here). A lot of the basic standard configuration can pulled into here.  The whole modules section has developed nicely and can shine as a major part of it.  How to select and install an existing theme.  Site recipes can be moved here as well.  Perhaps a link to the case studies in the About section can be added showing how some existing sites were built compared to any generic recipes we have.  Best practices would go here.
If anyone actually starts writing and contributing documentation targetted at newcomers, then a newcomers config guide would be a section here.
 
+Customization / Theming+
This is the section where you go a bit beyond the basic download.  Have an intro page with an overview of the capabilities if you know a bit of php, MySQl, etc.  Here is where all the snippets would reside.  Pull the Theme developers guide out of the Developers handbook.  The theme developers guide being in the developers handbook confuses the hell out of folks and it can maybe help show  that themeing need not be developing, but knowing a little php or css is needed.  
 
Once people get their install going what's the first thing they want to do?  Build their own theme, not 'develop' code.  Now, it will be in an obvious location.
 
With the various snippets repository in full growth, perhaps it can become a place for more articles and such.  This would be the 'advanced site admin' section and perhaps we can lure people into entry level dev stuff without them realizing what they are doing.
 
+Developing for Drupal+
Slight reorg only at this point, some stuff is not well organized anymore given the various additions.  
 
+About Drupal documentation+
Though this might be as well suited as a section in the About Drupal area, it would be beyond the scope of my idea at this time.

I would be willing to do the work this weekend (or Friday), assuming I can schedule the time with my wife.  I figure a solid couple of hours to move things (aliases would not be changed).  I'd be available on IRC while doing this.  Then have a few someone's follow through with a fresh eye for fine tuning and discussing over the rest of the weekend. 
 
The intro to each section would have a paragraph about how to contribute a page and what kind of content goes into the section.
 
Let me know what you all think
 
-sp
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20051228/3eb534bd/attachment.htm


More information about the documentation mailing list