Handbook update -reorganization progress
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.