Drupal has a substantial amount of good documentation; the documented code as seen on api.drupal.org, the developers handbook and even the installation and configuration guide has lots of good stuff in it. It also has older stuff that doesn't get updated in a timely manner and can be confusing. The last major handbook re-organization was Jan 2006 and that was a substantial improvement. Currently, just the three main books would be over 1,400 pages printed out.

One of Drupal's strengths also leads to it's frustrations. Drupal is flexible, it is content centric, so you can accomplish a given task in multiple ways. This is something that can be very hard to have people find the time to document. For those who haven't spent time writing HowTo documentation, it takes a lot longer than one would first think.

So, the problem, long term sustainable documentation with Drupal is difficult. Drupal core moves and changes with each version. For many versions, most of these changes resulted in only minor cosmetic differences in the user interface and menu placement.

With the release of Drupal 5, these user interface differences becomes rather substantial. JQuery's addition to Drupal in version 5 actually expands the UI possibilities in even more ways. With Drupal 6 we will see more interface and additions to core capabilities.

So what to do? At the Yahoo OSCMS I discussed this with a lot of people and came up with a new plan for the direction of some of the documentation and have been working on it since. For an identified base documentation we will use DocBook v5, commit it to CVS and version per Drupal release and generate PDF's in addition to having it live online in the handbook.

DocBook!? Doesn't that raise the level of difficulty to contribute? Yes and no. Yes in that DocBook will be required for this core set of docs and updates to it will be treated like Drupal core updates, very few will have rights to commit to it and it will remain focused on that. No, in that this will not cover every scenario and there will still be a strong need for continued community contributed documentation that can be more specific to various scenarios. The handbook will be re-organized some to accommodate this, the end result is still being worked out but will be coming to a handbook near you soon.

This documentation will be a select core set of docs based on an expansion of existing documentation. I have added significantly to the install and configuration steps (yes, including screen shots). In addition to the existing documentation there are some Drupal concepts that get repeated questions and are not obvious. Articles written by members (I can coerce) will be included in a reference section at the end. If they are not updated or relevant, they will be removed from the next version.

The core around these docs will be expansion on the;

• INSTALL.txt
  • INSTALL.mysql.txt
  • INSTALL.pgsql.txt
• UPGRADE.txt
• Default "Welcome to Drupal" instructions you get when you install your site
• Existing module help text

These will be fitted into a basic framework

• An introduction to the Drupal project (These documents will be available in PDF for download and this stuff is important and often asked in the forums)
• Before you start. Requirements, terminology, basic best practices.
• Installation. Expands on the install.txt and includes a basic configuration set for new sites with pretty pictures
• Basic content management. Various basic methods to post content, create menu's with just Drupal core.
• Administration. This is primarily every Drupal menu option if all your core modules were turned on.
• Upgrading your site. From the upgrade.txt
• Concepts. These are various collected articles on various Drupal concepts that can help new people to better leverage their new site. This section is transitory per version. If an article isn't updated or relavant, it won't be included in the next version.

I want to note, this is not a finished set of docs (I'd say almost alpha, almost beta). It still needs some editing, I have some feedback that isn't incorporated in yet, one or two outstanding requests for articles, there are some ugly sentences in it and the PDF generation has a blank page or two. Overall, I believe this represents something that we can commit to updating when a new version of Drupal comes out. We may not make the release date of Drupal 6 this time around, but I believe we will be close.

And no I have not upload it to CVS, it's been a longer week than I had planned for but it'll get there any day now so enjoy the preview and I hope this is something that people can get excited about and support.

I dedicate this first round release to my wife. Without her allowing me the time to write this, it wouldn't have gotten done.

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

AttachmentSize getting-started.pdf1.43 MB