I have been reading with interest the discussions at http://drupal.org/node/337079 and http://groups.drupal.org/node/15965 which both basically deal with the fact that Drupal has versions, and with each version comes a new set of changes both for procedural instructions and code samples, yet the Drupal Documentation can't handle changes in the same way.

So I came up with this idea. Let's continue the process of making a single page in the Handbooks for an idea, such as "Checking Code Out Of CVS", but then use jQuery to toggle hiding for all version-specific info of code snippets or explanations which don't pertain to your current Drupal version. "Overriding Theme Functions". That's a concrete task. "But overriding for which version of Drupal?", you ask? Well, follow along as best you can and I'll try to explain.

Let's build a Versionary Switcher! First, in the Handbook page we'll create a set of <code> tags around each snippet that needs to be displayed. Note that this will work for all manner of text as well, but I'm demonstrating code snippets first because it makes things easier to grok.

"...here is some text that's explaining why overriding theme functions is cool, desired, a good idea, and will allow you to keep both your arms..."

<code>
<?php
function _phptemplate_variables($hook, $vars) {
  switch ($hook) {
    case 'page':
      // Sample code code goes here.
  }
}
?>
</code>

<code>
<?php
function phptemplate_preprocess_page(&$vars) {
  switch ($hook) {
    case 'page':
      // Sample code code goes here.
  }
}
?>
</code>

"...and then this Handbook page would go on to the next section where users will learn how to change the name of a theme function before pasting it into the template.php..."

Each of the above code snippets are functionally identical to a user who's trying to learn how to create a new variable in their page.tpl. The only difference is is the way they are named. In a user's eyes, they'd really only like to see the version of this snippet that pertains to them *right now*. CSS can help. We'll add drupal version classes to each of the code tags, like this:

<code class="version-d5">
<?php
function _phptemplate_variables($hook, $vars) {
  switch ($hook) {
    case 'page':
      // Sample code code goes here.
  }
}
?>
</code>

<code class="version-d6 active">
<?php
function phptemplate_preprocess_page(&$vars) {
  switch ($hook) {
    case 'page':
      // Sample code code goes here.
  }
}
?>
</code>

Next, we'll need a way of marking up a set of tabs/menu-items/links/whatevers so that users can switch to the version they're interested in seeing.

<ul class="versionator-tabs">
  <li class="versionator-link"><a href="#">Drupal 5 Example</a></li>
  <li class="versionator-link"><a href="#">Drupal 6 Example</a></li>
</ul>

Once the tabs are laid out into a horizontal menu, the code tags are all hidden by jQuery after the page loads, and the most recent stable version of Drupal is automatically selected for the user, we've got ourselves a tabbed versionator that can rotate through one, two, or even ten different versions of example code as Drupal grows!

All the code samples (or version-specific instructions) remain with the Handbook node, thus alleviating any concern that some instructions may get updated while others are forgotten. And think of how cool this would be for writing HowTo tutorials!

Sweet! I'm gonna go post this into the Drupal Documentation issue queue and await the firestorm of dissenting opinions. I love blogging early in the mornin'.