As announced in the documentation team mail list, I've been re-organizing the handbook. A lot of work has gone into this since I started last week and I have come to the conclusion that we have a lot of content. Hopefully some of it is easier to find. I thought I'd mention that this is still an ongoing work in progress and probably will be for the rest of this month.

History

The handbook is actually five separate books using the book module. When I started they were named: About, Installing and upgrading, Configuring and customization, Developing for drupal and About Drupal documentation. The basic structure has been in place for a long time. Looking at this by title alone, it's sort of difficult to know where to start if you're new. This made it harder to find information, and where to add something if you did choose to contribute.

We have had a lot of additional content in the last year that has just sort of evolved into place. The php snippets section (started off by Dublin Drupaller) which has led to an even wider variety of ideas and suggestions. The online modules and features help text to all Drupal core modules and many contributed modules (a major concerted effort lead by Kieran Lal of CivicSpace). These have been availbable for several months now.

Structure

At this point About Drupal and About Drupal documentation sections will remain as they are. I renamed two of the other sections and moved a lot of content to suit the new names.

  • Installation and configuration: renamed This section is now all about installing and configuring Drupal out of the box. If it can be done with core or contributed modules, then that's what will be in here.
    • Several nodes were given more descriptive titles and additional introductory text. Many pages have been grouped, ordered and placed together.
    • The titles Introduction was changed to Introduction to Drupal terminology.
    • All installation related pages have been placed together and an introduction added under Installing Drupal, modules and themes. Hopefully, this introduction will help guide folks as they take their first steps as Drupal administrators.
    • Configuration has been renamed to Basic site configuration and is mainly about configuring the Drupal basic options that are not separate modules. Admin >> settings, changing user login, etc.
    • Drupal modules and features now contains online help for all Drupal core modules and for many contributed modules as well (hint, we need more folks, so pick your favorite module that's not there and start writing).
    • Best practices guidelines to help you maintain your site.
    • Troubleshooting FAQ This is one of these must have sections and it's been around a while. It's been moved here and has some good answers to many common questions. There are more common answers that need to be added, so let's mine those forums for common questions.
    • Upgrading from previous versions, Migrating from other software and Tuning your server are self explanatory.
  • Customization and theming renamed This section will be all the fun things to do to customize your Drupal installation. You can do a fair amount with an out of the box install, but to truly make your site different, you need to play with a little html, php and SQL. The theme developers guide has been moved out of the developers handbook to here. It didn't really belong there anymore and making your own theme is one of the top things people want to do. Also, most people couldn't find it in the Developers handbook.
  • Developing for Drupal will continue to serve as a source for developer oriented content.

At this point, I've only really made significant progress in the Installation and configuration section. I underestimated the time it would take. There was a lot more content there then I realized.

In addition to moving and organizing content, some very old content has been unpublished. A lot of comments in the handbook have been incorporated into the content or removed per the comment guidelines.

Kieran Lal has been busy culling old comments by the score and continuing to add additional content.

We've had some other folks jump in and help out as well and gracefully allowed me to hijack them to bounce opinion or help evaluate comments;

  • heine, helped review and identify duplication and verbiage and comment culling.
  • oNyx, feedback, bounce ideas and phrases. Made him read things
  • fgm, found some very old definitions in the terminology section so we spent a bit of time updating them.

I hope to begin the Customization and themeing section by the end of the week and the developers handbook before months end. This work is not done in a vacuum. You can click create content / book page or, go to a handbook page and click the add a child page link. In order to improve our documentation, we need people to write some. By people, this means the community of users and developers. This means you.

So, how can you help? Drupal is Open Source software. It relies on your active help and contribution. There are a number of ways you can help.

  • Answer questions in the forums, if you find you are answering the same question more than once, add it to the handbook.
  • Adopt a module and add documentation to the handbook.
  • Join the documentation list.

Comments

robertDouglass’s picture

Sepeck, you are constantly encouraging people to jump in, contribute, help out, and make Drupal reach its potential. This initiative sets such a good example on how to participate, and creates real value for all Drupallers. Thanks to you and everyone who helped out!

- Robert Douglass

-----
My Drupal book: Building Online Communities with Drupal, phpBB and WordPress

my Drupal book | Twitter | Director, Product Operations Commerce Guys

Dries’s picture

Kudos to Steven Peck and Kieran Lal for their hard work on the Drupal documentation. You guys rock.

EffieRover’s picture

May I please request that a list of canon variables be included or organized somewhere that is easy to get to? I have taken to skulking through the code to find simple things like variable_get('site_name', 'yea') ... what standard variables are available and how are they accessed? This would include GET and POST arguments (which I recently found hiding under php snippets).

Thanks!

Steve Dondley’s picture

grep (see google), or some similar function if you've got an advanced text editor that can search across files (like Ultra Edit), will help you a great deal.

Also, drupaldocs.org might also help you and a peek at the database (in the variables table) will help.

It would take quite a bit of work to track the variables in Drupal. Would you be willing to help start the list in the handbook?

--
Get better help from Drupal's forums and read this.

EffieRover’s picture

By skulking through the code, I meant grep. I still have to look to make sure that it actually contains what I want and not something related. I don't seem to be able to make heads or tails of the variable table. I can list what I find by trial and error; won't promise it will be complete but it will be a start ... gimme a page to put them on.

travischristopher’s picture

newly released for 4.6 http://drupal.org/project/devel it adds a nice variable viewer to the admin Nav block.

Travis Christopher
Senior Web Designer
http://www.fame4art.com

kae’s picture

thank you. sounds very useful

moshe weitzman’s picture

there is a variables module which lets you view *and edit* this table via admin page

kae’s picture

that's terrific! thanks for letting us know.
ae2005

Dries’s picture

Feature requests for the handbook should go here. :)

kae’s picture

Dear Sepeck,
Thank you very much for the tremendous work you do in overseeing the reorganizing the documentation. The changes you made sound like a very logical reorg. I'm sure it's a huge job. As I've started trying to write some documentation (unofficially) I see how hard it is to write so that everyone can understand it.

The questions of monthly billing of paid memberships comes up over and over. I've written a summary of the most relevant nodes and put them up here.
http://drupal.org/node/44300

22996 module author did not reply. may not be supported
43609 can't edit or delete subscription
14434 Dries favors having a good paypal module
35718 readme.txt unclear; no success
24441 got it working (June 2005)
42434 got it working (Dec 2005)
32187 ecommerce module only does recurring invoices; does not do automatic payment via credit card (Sep 05)
37802 use ecommerce module for recurring payments (Nov. 05)

In that same node, I raise the idea of having a place in the documentation where users can add comments to the contributed modules. For example, on this page http://drupal.org/project/paypal_subscription
the summary above could save users an enormous amount of time. If we users are allowed to add comments like this, we could add a lot of documentation. Some of it could be wrong, but the reader would be told that, and it's better than reading every bug report and researching from scratch.

I hope you will consider that.

Drupal is terrific with an amazingly generous core team.

thank you so much,
ae2005

Boris Mann’s picture

See http://drupal.org/handbook/config/contribmodules -- paypal_susbcription isn't listed, feel free to add that page. Summary as listed would likely be best as a comment or even as a sub-page.

kae’s picture

If I add that page, how who would edit this page to include paypal subscriptions?

Amazon’s picture

sepeck’s picture

What we need for the documentation is not the links to the threads. We need people to go through the threads and pull the information out into a readable format. So that they have their information in one place. So, rather then looking at a number of different forum posts, new users can look at one or two handbook pages that lay eveything out.

So for an example...
profile modules. It has a main introductory help text. It then has broken out three sub pages with additional information on how to use it.

So, collecting related forum links is good. Now that you have them, try to pull the informative content from them and post that content to the handbook in the form of a book page. Pulling the actual relavant content from a discussion and presenting it in a useful manner is the challanging part.

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

Dublin Drupaller’s picture

I have a module I'm working on that might help...it's for a client but it should be okay to contribute it in.

Called discussthis.module it's a very simple module that inserts a link at the bottom of specified node types that automatically converts them to forum topics.

It wouldn't take too long to tweak it to be a CONVERT THIS POST TO A HANDBOOK PAGE link...so it automatically converts the forum post/comment into a new child page that can be edited and appropriately categorised.

Will that be of use?

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

kae’s picture

Sepeck,
I fully understand the need for what you describe. Yet I think there is also usefulness for what I describe. When I am researching a problem, I don't just want a 3 paragraph summary, because it may not go into enough detail. If there are links to the best threads, then I can read 20 pages instead of 1, and either use the facts or logic presented to figure out the answer to my problem. You of course see that 3 paragraphs simply cannot cover enough of the questions that people ask. And of course the handbook page may not cover 4.7. Having a page of links to threads can also help people try to sort out their problem by version. Right now I have to read or skim every thread in the search results every time the handbook page does not answer my question. Even if I get an answer in the first thread I usually have to keep reading because I'll often find out that the answer in one thread is wrong.

thank you for taking the time to write,
ae

cel4145’s picture

There is no reason that the handbook pages can't have more than just a 3 paragraph summary for a given topic. Someone just needs to write more detailed documentation when they find this to be the case.

Ultimately, the handbook could be better improved if people who use the forums for knowledge gardening--such as yourself--would write up what they learn as they go along and add it to the handbook. This makes it easier for those later on to find solutions to the same problem. If every user/developer who gardens the forums would write up what they learn just one time out of five and correct the handbook when they find a mistake, in no time at all Drupal would have a fantastic set of documentation.

Dublin Drupaller’s picture

this is superb work Sepeck. Nice one.

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

sepeck’s picture

There was a lot more existing content then I realized. Culling through the comments also took a tremendous amount of time. At the time I posted this, I think I personally was at around 50 hours of time since I started Tuesday. I suspect Kieren was at a similier level. So there may be occasional days where not much happens as I take time off to catch up on my World of Warcraft play time :).

In any case, some folks will have to go through and follow up on some of my initial decisians on placement to fine tune things. Choices that made sense while in process may not make sense two weeks later.

I am also still working through some ideas for the Customization and theming section to allow for contributed growth to continue in that area... Snippets can be more then php or theming so trying to figure out how to lay it out understandably.

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

Dublin Drupaller’s picture

Hi Sepeck,

can I recommend this proposal to approach theming on a modular basis?

the logic is based on the success of the slice bread snippets. i.e. at the moment Drupallers appear reluctant or have time constraints to contribute themes back to the site..however if they were able to contribute modular theme snippets, I think it would be more fruitful.

By theme snippets, I mean 2 main categories:

(a) style CSS snippets
- page layout style snippets
- menu styles
- block styles
- blog styles
- table styles
- whatever style snippets...etcetera

(b) theme engine specific snippets.
- phptemplate snippets
- node-blog.tpl.php snippets
- node-image.tpl.php "
- user_profile.tpl.php "
- image_gallery.tpl.php "

I have already started the above with Example - Theming the user profile pages and the User profile page Snippets.

Both of which are becoming populated already...

the only drawback is that the handbook doesn't lend itself well to a "snippets repository". Ideally we should look at maybe setting up a simple flexinode.module content type for snippets that allows:

(a) title + brief description + requirements + compatibility
(b) visual representation (screen shot)
(c) pasted code
(d) comments.

I volunteered before christmas to look into that, but, have found it difficult to find the time.

The bottom line is the concept of contributing snippets appears to be a winning one. And adopting that to a dedicated theme-snippets section as outlined would bear fruit me thinks.

While the idea for a theme comp. is great..we shouldn't need enticements like that for people to contribute their themes.

if it's on a modular basis...not only is it easier to contribute, there's less worry about "all the sites are going to look the same as mine"..

to quote from my proposal:

Instead of more themes..I'd like to see the emergence of a CSS & TPL snippets repository, where the contributions are more modular. i.e. Template (TPL.PHP) snippets with accompanying CSS style snippets to make your blogs, comments, blocks, menus, footer etc. etc. look a certain way.

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

kae’s picture

Thanks everyone for your comments. I don't understand Dublin Drupaller's module, but I want to stress that the key is to find the best posts (and weed out the incorrect answers). I go through some 300 comments for a typical question in order to find the most relevant answers.

As I wrote a few comments above,
http://drupal.org/node/44233#comment-82526
I think links to the best threads are really useful for those who want to research a subject beyond the 3 paragraphs in the handbook.

Newcomers like me simply cannot write handbook pages. We might write something that is wrong. But we could point others to threads or comments we found useful and to us sounded right (but could be wrong).

thank you for taking the time to consider this issue.
ae

Dublin Drupaller’s picture

Hi Ae

I don't understand Dublin Drupaller's module

It's really simple AE...forum topics usually follow this general pattern:

1. Person asks question
2. Someone replies with an answer.

the module idea is to have a CONVERT THIS TO A BOOK PAGE link at the bottom of threads, so, when the questioner gets their answer, it's made exceedingly easy to convert the answer (forum post) to a Book page (for the handbook).

it's designed to simply encourage posters on the support forum, who get answers, to inject the answers into the Drupal.org handbook.

I hope that makes sense..

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

kae’s picture

Dub,
I see. Thank you. My first reaction is this could work out really well. If we do this, I'd suggest something like, "if you think this thread gives a helpful answer and belongs in the handbook, please click here to link this thread to the right page in the handbook." otherwise, some newcomer might do it too often.

linking threads to handbook pages makes sense to me. that would reduce the flood of questions who haven't figured out the best way to search this site.

thank you for working on this idea! (and then if we applied the moderation queue or some rating system, we can try to have the best threads float to the time.)

I also want to say I am amazed by your generosity in answering people's questions and contributing. your exceedingly patient and detailed answers for the person trying to use flexinode the other day really made me think, "this should definitely be connected to the handbook! There should be a way to do this." thank you so much for your vital contributions to the Drupal community

ae2005

ae

sobe’s picture

Perhaps you could set that up so it was like the spam button on craigslist where if a certain number of people click that link then it gets put into the handbook, but until that time it stays where it is.

sepeck’s picture

We can already add forum topics to the handbook. The problem that was discovered with this approach was that it 'moved' the forum and it's thread to the handbook. This then made the handbook itself into a forum. People then kept posting support questions in the handbook.

Information is hard to parse. Which comment does a user refer to? Which opinion/solution do they use? This is why links to useful threads don't really work. The information needs to be distilled and consolidated so that the quality information is more easily available. All new pages by defualt go into the moderation queue for review by team members. This allows for correction, so even a person new to Drupal can take a shot at it....

One posilbility being discussed is to open up the editing of the handbook more. [NOTE: This is a discussion only at this point.]. 4.7 (drupal.org not currently on it) has some enhancements to versioning that make this a more realistic posibility (more wiki-like in behavior, less impact on the db). There is a usabililty patch or two that needs some tuning first before that discussion really gets going. Also, I'd like to finish the structural stuff and hold off until Drupal.org gets updated. It's all moot until we test how it works.

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

oc’s picture

This is a great project!

However it could be even better if a couple of additional reorganizations took place. The first thing is that the various modules are all lumped into one support forum. The support forums should be reorganized to eliminate the "general" category and then the categories of the forums should mirror the main chapters in the handbook. This would make it much easier to find discussions about the area of Drupal that you have questions about.

Then, each module download page SHOULD INCLUDE A LINK TO THE SECTION OF THE HANDBOOK THAT DISCUSSES THE MODULE. Currently, most of the module pages that I see don't tell you whether there is any useful info in the handbook at all. So many times I don't bother looking in the handbook even where there is lots of useful info there.

-rich

Organizers' Collaborative -- Free Software for Activist Groups
http://organizerscollaborative.org and http://organizersdb.org

Organizers' Collaborative -- Free Software for Activist Groups
http://organizerscollaborative.org and http://organizersdb.org

cel4145’s picture

+1

This is a really good suggestion. Of course I say this without knowing how hard it would be to add this into the project module. Perhaps you might file it as a feature request with the project module?

Dublin Drupaller’s picture

Then, each module download page SHOULD INCLUDE A LINK TO THE SECTION OF THE HANDBOOK THAT DISCUSSES THE MODULE.

I think the handbook should be not be the place for discussions. It will get unweidly very quickly.

I'd prefer to have a forum sub-category for each module...where discussions take place and feature requests/issues get promoted from there to the existing project.module feature that allows that.

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

sepeck’s picture

The addition of the modules help to the handbook only occurred a few months and was not publisized well. I believe the goal is that site admins will have live links from the help system in their sites install to then drupal.org handbook.

There are several hundred modules being manged by project and I know that I am not going to update each of those projects. Not all modules have handbook pages as we have insuffient volunteers to provide the information as is. This is like suggesting more work for volunteers we don't have to complete. If module maintainers wish to add a link to any exising handbook docs, then I think that will be best left to them.

Consider that you are asking for an additional 200-300 forums to be created. I don't think anyone has run metrics for the forums module performance under such a scenerio. There are many places to discuss a module. For features and issues, the project page for that module has a place. The general forums will also get you more eye's. In paticular more eyes that may use the module in combination with other modules that you hadn't considered.

This re-org of the handbook and announcement is to GET YOU TO LOOK in the handbook for this useful information. It's an addtional three clicks. Please, this is a volunteer effort. This is something I and others do in my spare time and I only have so much free time to spend on it. I and others cannot hope to do everything and still take care of the important ones in our lives to save you three or four mouse clicks.

To put your request in context. I have over 50 hours in this handbook re-org at this point since last Tuesday. This does count the hours of others.

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

kae’s picture

Sepeck,
You are definitely one of the Drupal heroes! I have no idea how you manage to work/organize the handbook and have a life. Just this morning even before I read your post I was thinking you must be an extremely effective and efficient person. (And every day I see you post a lot of useful comments in the forums directing people to the proper page in the handbook.) Seems like managing the documentation (not to mention answering questions in forums) would be a fulltime job by itself in software that costs money. Thank you so much for taking in this absolutely critical job. Sorry if people keep giving you suggestions without expressing enough appreciation for all that you do. If there is a Drupal hero award you should definitely be one of the recipients.

ae2005

Dublin Drupaller’s picture

Just to echo the other plaudits, I just thought I'd post a well done message and mention that you're fire fighting isn't going un appreciated.

As an addendum to my post up above, I'll do my best to find some time to flesh out the bigger picture strategic ideas I mentioned which will reduce the need to get into fire fighting like this in future. I will keep it simple and logical, so it's easy to implement and adopt.

Fair play to you..

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

wpd’s picture

I appreciate the hard work of all the documentation contributors. It is easy to overlook documentation in any project, but it is often the vital difference between love/hate for the end user!

I also find it confusing that there is not a link between the handbooks and the modules. I think there should be a link both ways.

I wonder if there is a way to do this automatically?

White Paper Designs

sepeck’s picture

I did take a look. There is a space in the project module for the contributors to include a link to documentation. Traditionally for contributors it was left blank for reliance onthe readme.txt or a link to their own site.

I think perhaps the module contributor guidelines will be updated to suggest that either the module contributor add or work with the docs team to add basic instructions to the handbook and if the contributor still wants a link to their site, we put that in the handbook page with the basic help text. (well, my thoughts at least).

We do not currently have text for all the modules but over the next few weeks we can ask the module contributors to look at adding the information to their page or add it for them. It's something that shouldn't be missed if it provides a direction for people to go to gather information.

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

kae’s picture

How about this? I've been thinking about setting up a sandbox for anyone can go test out 4.7 and look for bugs. We can also use that site sort of as a sandbox for documentation. People can write stuff. implement some of the ideas that have been suggested here. and when we find good ideas we can transport them over here.

I just realized we'd actually need 2 sandboxes. otherwise, one experiment in the 4.7 sandbox and wipe out the nodes!

This is great!!! someone had the same idea and put up a demo site

http://drupal.org/node/44486
drupaldemo.org

now everyone can come to the bug fix party!

ae

sepeck’s picture

http://drupal.org/node/28245

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

kae’s picture

sepeck,
thank you very much for the link. I had stumbled into the sandbox just 24 hours earlier, but had not seen any documentation for it. this will be very useful. kieran made a paypal subscription link in the handbook. I'm trying to get it working. once I do I'll try to write some official by the book documentation!
thank you for all your contributions,
ae2005

wwicko’s picture

Thank you to sepeck and the rest of you who have undertaken this task. There is so much useful information on this website, and yet, as everyone here already knows, it can sometimes take hours to wade through the swamp of misinformation to find an answer to a simple question. This effort to clean up the docs will likely save an immense quantity of person-hours among all Drupalers.

As a user, this news is as exciting to me as the recent news of 4.7 beta releases.

Also, thanks for the tips on how to contribute to the docs. I think maybe the the gist of this comment...

What we need for the documentation is not the links to the threads. We need people to go through the threads and pull the information out into a readable format. So that they have their information in one place. So, rather then looking at a number of different forum posts, new users can look at one or two handbook pages that lay eveything out.

So for an example...
profile modules. It has a main introductory help text. It then has broken out three sub pages with additional information on how to use it.

So, collecting related forum links is good. Now that you have them, try to pull the informative content from them and post that content to the handbook in the form of a book page. Pulling the actual relavant content from a discussion and presenting it in a useful manner is the challanging part.

...would be helpful early on in the Documentation Writer's Guide.
http://drupal.org/documentation-writers-guide

With these guidelines, and having waded through the swamp several times now, I think I might just have enough confidence to take a stab at consolidating some related posts, comments and maybe even an existing handbook page or two and writing some documenation.

Thanks again!

kae’s picture

I've been trying to get paypal subscription to work and have tediously logged all relevant threads and info at node 44295. Fortunately, others have jumped in. I've promised kieran that I'll try to write a page in the handbook once I have it working. (I'm still in the sandbox right now.)

I'm posting here because I think this is an example of a really valuable thread that I think it's good for the handbook or the module to link to in some way. Two reasons:
1) the info becomes available immediately, and does not depend on my getting it working live and taking the time to write it up
2) even if I write it up, the 3 paragraphs recommended length could not be as helpful to people struggling with a problem as the 10 pages of text (according to my word processor) that's available on the thread.

I've copied over the content of my last post to give you a sense of the flavor:
http://drupal.org/node/44295#comment-87670
if paypal sub is not working for you, here are some things to try:
here are the changes i made yesterday:
1) changed paypal settings in drupal: set on libcurl (default is fsock). i confirmed libcurl is compiled into php by asking my hosting provider (if set incorrectly, this will cause the "invalid item id number" error)
2) changed customer service email on paypal to match developer/webmaster addr
3) inserted sandbox into url in paypal settings in drupal (this tip only if you are using paypal's developer sandbox)
4) earlier, synchronized all email addresses across drupal and paypal
5) took any numeric characters out of product description on paypal and on drupal.
6) (had done earlier) make sure administer subscriptions is enabled in access control

ae2005

Dublin Drupaller’s picture

appreciate the effort you're putting into this sepeck, but, I have to say, re-organising the handbook and calling for more pages is not actually going to make much difference.

What would be far better is to improve the pages that are already there.

The handbook should be primarily instructional. Unfortunately, many try to be educational. Many more are just copied and pasted forum posts with very little editing.

If I could suggest a slightly different approach, instead of spending hours reorganising the handbook..can I suggest you target LONG HANDBOOK PAGES and handbook pages with a lot of comments?

Take those LONG HANDBOOK PAGES and split them into seperate, shorter pages.

Let me give you an example,

Have a look at this handbook page: Customizing themes for node types, terms, sections, paths, and front page

And now look at the edited versions:
Part I: Customising the full page layout and sections based on node type
Part II: Customising the full page layout and sections using CSS and unique BODY Class & IDs
Part III: Customising the full page layout and sections based on path and taxonomy terms

the difference is subtle but seismic. the point being that the handbook is underused because the quality of the pages need to be improved, rather than shuffled about.

Please take that as constructive..we all really appreciate the effort and energy you're putting in, but, it's better to have less better quality pages rather than more pages just slapped in there.

I think taking existing pages (especially the most popular handbook pages, such as the installing drupal page should be split into seperate, bite sized pages which are more instructional and less educational.

I notice that other drupallers follow by example..i.e. since I started the new PHPTEMPLATE Snippets Section I notice that others are not only contributing, but following the easy to follow, 1,2,3 instructional type format.

I maybe wrong..but if the energy was focussed into improving existing pages rather than reorganising them, it might bear more fruit.

Just a suggestion..

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

sepeck’s picture

Yes and no. Please sign up to the docs list and follow the arguments for and against long pages. As it is, the Installation and configuration section is now easier to logically follow. I added a total of five pages. Everything else was there. Now, people are finding things. People can see pages and begin working on improving individual pages. There are those who think fewer longer is better and those who feel more shorter pages is better. I'm not there yet, I'm working on structural to improve visibility and make it easier to find things. If people don't know that they were there, they can't improve them.

As it is, your new section actually duplicates an existing section. Your new section also assumes that phpTemplate themes should be on the top level. That kind of made me pause on that handbook while looking at where things are going. We now have http://drupal.org/node/19854 and http://drupal.org/node/45471 which are essentially the same thing.

Part of the delay is I have to write some 'approach' landing pages so that we don't have to repeat in the forums the same verbage over and over again. Which you and several others have repeatedly said in post after post. I would rather, point them to one page and then answer/clarify questions on various approaches that new folks have. This type of explanation is by it's nature more complex and harder to write.

So, your new activity could not have and would not have happened without my re-org. Themeing as a whole was lost in a subsection of the development handbook. Now it is part of an approach to your Drupal site. Currently, the Customization and themeing handbook is scattered and not logical. Assuming I get no calls from work this weekend, some of that will change. I will note that contributions to the PHP Snippets section has been ongoing and active for a while now.

As to 'long pages' with lots of comments? Keiren and I have gone over and integrated well OVER 300 comments EACH into handbook pages and others have gone through as worked on pages as well. I draw you attention to this link called handbook comments. You will notice that no page has more then 18 comments (when I looked). Before we did this there were a lot of pages with substantially more. Feel free to also go through, incorporate those very same comments into a page and remove them per the handbook poilcy. You have the rights to do so.

As to the installing Drupal.... That is the install.txt page. I think that page needs to stand as one page. I think that sub pages that expand on it are good and exist. Do they need improvement? Sure, I don't have cPanel so someone will need to review that page.

Please sign up to the docs list where discussion is ongoing on this.

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

kae’s picture

sep, what a great link! thank you. I also found this.

http://drupal.org/handbook/most-popular-pages

which is exceedinly useful. in fact, i might think it's the single most useful page on drupal.org

It would definitely go on my list of "pages that i think the drupal.org site should link to on top of the front page."

ae2005

Dublin Drupaller’s picture

Sorry Sepeck..perhaps I didn't make my point clear enough. I'm already a member of the docs mailinglist, I was responding directly to your forum topic about RE-ORGANISING THE HANDBOOK and thought I would offer my two cents on that. I assumed that by raising the topic on the forum you were opening a discussion rather than just telling us how it is.

My point is that shuffling the sections/pages about won't help matters much. It's the quality of the pages themselves that need improving.

I started the PHPTEMPLATE Snippets section to move instructional pages away from educational pages (i.e. the phptemplate developers guide, which explains the concepts and principles behind the theme engine). I'm not surprised, that at the moment that means some duplication, but, please note that the new section is a work in progress.

Hope that makes better sense..I don't have time to discuss the merits of long/short pages, when I was working on the phptemplate snippets section, it just struck me and worth mentioning. I notice that you are putting a huge amount of time and energy into the re-organisation process..when in fact it might be better directing the energy in a different direction. And it's only a suggestion.

I'll drop you an email when the new section is complete. I'm adding pages slowly to ensure that what's added is of value and concise. the handbook is full of pages that are simply copied and pasted without much further thought. which is something I'm trying to avoid.

Apologies if I have confused. Keep up the great work.

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate

sepeck’s picture

Ah. The re-organization helps expose the content, so I think it needs to be done on a 'bulk' structural scale to get us started. As a result, we have exposure to the pages that have not been viewed for a while. There will also be fine tuning of it as well. Some of my choices will prove not to work, but we had to do something so I threw the rock in the pond. My main goal was to make what we had immediatly more accessable and then people could help see where we need to go next, so I agree, need to improve pages and fine tune location.

As to pages that are copied and pasted, yep, they're in there. They need improvement. So, now we're down to long pages that read from beginning to end on a given topic, or short pages where you can pick out headings inthe book links on the left side. I think that discussion should definitly go on and be decided. For the handbook, I like smaller bits with descriptive title's and logical grouping. It makes it easier to find that piece of information you are looking for later. Others don't like that. I suspect that which pages get broken up and which pages don't is going to be down to a combination of what the topic for them is/was and who volunteers to do the work on it.

There is also a lot of content that is beneficial even in it's stunted state and hopefully it will provide a nice starting point/framework for someone to edit/improve.

But my inital goal wasn't to necessarily to address individual pages, but the structure of the existing content. I have been working on indivdual pages for a long time and overall felt we weren't getting anywhere. So yes, editing and improving individual pages definitly needs to happen by people. The way I read your post was that you thought editing content should be done first. I think that defining the structure will help aid in directing the editing of the content by ordering it and helping define what the various sections are. Now it's more visible so hopefully people will take this opurtunity to improve their pages and area's that they are interested in.

I'd kind of like to see some folks (individuals and teams) take 'ownership' of sections. This would allow them to feel they had more control over a given section and make it more likely they would improve the pages. Aslo, it would give folks with ideas for improvements an initial point of contact and the rest of the folks on the docs list a check in point for anything they'd like to do.

I want to chat more on your ideas of instructional vs educational. It may be a way of defining a division of content for the Customization and themeing section that I have been thinking of.

-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain

Dublin Drupaller’s picture

no worries..appreciate the hard work you're putting in...just thought it wise to nudge you in a more efficient direction..

if you use the new PHPTEMPLATE SNIPPETS SECTION I have started as a model, it should be self explanatory.

Educational page = opinions, overviews, concepts.

Example of an educational page - PHPTEMPLATE ENGINE

Instructional page = A specific Solution followed by 1,2,3. nothing more and as little preamble or life stories as possible.

Example of an instructional page - Admin theme switcher snippet.

An example of what's happening at the moment with the documentation is:

(a) forum topic starts
(b) solution is found
(c) solution + variations are pasted or lumped into the one book page.
(d) preamble, educational, instructional and opinion is all slapped in together into one book page.

User experience is:

(a) found a page in search that relates to what they want to do
(b) deciphering and seperating the preamble, educational and variations from what the instructional solution is takes too long and drives them to the forum to post a duplicate.
(c) process repeats, i.e. (A) forum topic starts...etcetera.

So the handbook is getting a lot of pages inserted..but, individually, the pages are only semi-useful.

As an example of converting existing handbook pages as outlined above to an instructional/educational format, have a look at this handbook page: Customizing themes for node types, terms, sections, paths, and front page

And now look at the edited versions:
Part I: Customising the full page layout and sections based on node type
Part II: Customising the full page layout and sections using CSS and unique BODY Class & IDs
Part III: Customising the full page layout and sections based on path and taxonomy terms

if you use new phptemplate snippets section (that's a work in progress) as a model, you should be good. There are one or two concept type pages within that section..but, I'll extract those out and tidy it up when it's finished and ready to go.

Have a gander at the Concept behind the new PHPTEMPLATE SNIPPETS SECTION..it should give you an idea to where it's going.

As mentioned I'll drop you an email when it's close to completion so you can keep up with what's going on.

Dub

Currently in Switzerland working as an Application Developer with UBS Investment Bank...using Drupal 7 and lots of swiss chocolate