Prevent docforking; What if we could show all version specific info on a single Book node? [#339456]

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:

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!

Comments

Comment #1

leehunter commented 26 November 2008 at 17:36

I think it's an interesting idea but I have some reservations about how well it would work in practise and whether it would really scale.

Consistently applying version tags to small chunks of text can be a bit of a challenge, especially across an ad hoc group of contributors. If someone misplaces a tag, a chunk of text could quietly disappear without anyone noticing for a long time. I've done a fair bit of this kind of versioning using FrameMaker and I've found there can be lots of little glitches until people get the hang of it. And keep in mind, that that's working with a GUI that's specifically designed for that kind of markup, it would be much more fussy tagging versions directly within HTML. Incidentally, I've never seen this done across product releases, it's more typically used to mark up content that has variations for different platforms.

I'm also wondering whether pages might get very long and hard to edit if by say Drupal 9, the person editing the document has to scroll through screen after screen of old versions.

I'm not saying we shouldn't do it, but I wanted to note that there are some practical isses which would need to be examined before we went too far down that road.

Comment #2

HansBKK commented 26 November 2008 at 19:12

I agree that although a great concept, it would only be practical to implement when a small set of trained editors are adding content. With visitors from the community adding/editing pages, the barriers to entry need to be set quite low, as with just creating a node and tagging it with a version term.

I also suspect many if not most contributors won't necessarily know what applicability their contribution would have beyond the one they're working in at the time.

Comment #3

senpai commented 26 November 2008 at 19:19

Well, Hans, you can't have it both ways. Gotta pick one. Either you want a great Getting Started guide, or you want little bits of easily edited plaintext saved in multiple related nodes which could get unlinked and moved at whim by anyone next week. Based upon your mailinglist comments, I'm not sure what your idea goal is now.

Lee, I'm listening quietly in the background here. Can you think of a more robust way to implement a versioned documentation system using the same modules we currently have at our disposal inside Drupal core? Let's hear your ideas.

Comment #4

leehunter commented 26 November 2008 at 19:47

I've been pondering this for a while and I don't know if I have anything close to a definitive answer.

At the moment, I'm thinking that the simplest and most robust solution would involve using something like Views to just provide filters to each handbook. We already tag pages by release number, so it would be trivial (I would guess) to show the reader a link that reads "Theming Guide (Drupal 5)" but that actually goes to a dynamically created view of the one real theming guide (with the D6 and later stuff filtered out by Views).

Each version-specific page should have the version indicated in the title (e.g. "Configuring a .info file (Drupal 6)").

If there are just one or two trivial differences between the way things are done in, say D5 and D6, they could be flagged in the text. I don't think the reader would have a problem with the odd notation here and there (e.g. "In Drupal 6 and later, click the x widget, in Drupal 5 and earlier click the y widget") but any substantive differences would require new pages.

Only doc team members would have the option of looking at the raw books with all versions of pages in place. This would be helpful in comparing books and making sure that all topics were covered in new book (as it is now, we have to flip back and forth from one to another).

Comment #5

HansBKK commented 26 November 2008 at 19:53

>little bits of easily edited plaintext saved in multiple related nodes which could get unlinked and moved at whim by anyone next week.

This is a good description of reality as it currently presents itself to us, and all considering it is surprising how well it does work, isn't it? I do try to express my thinking consistently, I'll try to clarify.

Within the above context, I've expressed that the books should be structured by role/topic, with any version-specific branching to take place at the bottom of the tree. That's my main point. Infrastructure solutions that still work within the limitations you point out would be most welcome, and in my opinion would be based on more thorough use of Taxonomy and then Views filtering.

I've often expressed that ideally a small team of trained editors would be creating/ maintaining docs. If that were to happen then sky's the limit on more effective presentation possibilities, and your solution becomes not only a great idea, but practical.

Comment #6

senpai commented 26 January 2009 at 22:38

Status:

Active

» Postponed

So what I'm getting here is that in order to accomplish a set of pages with version-specific instructions, yet without a completely separate set of handbooks for each Core version, we'd have to allow anyone the ability to create or edit the nodes that make up that content, and then assign a select group of people the ability to control the workflow of how those individual nodes are going to be organized and presented to the browsing user?

All of a sudden, I'm envisioning a set of triggers and actions (or rules.module) that lets anyone create a piece of content, but that node would have to become a part of a bigger node under the control of a set of Docs Admins. Sorta like O.G., but in reverse?

Organic Groups allows nodes to become the children of other nodes, but in a rather rigid fashion and in a topdown manner, but what we're talking about here is nodes becoming the children of parent nodes in a rollup manner, based upon A: their admin-defined relationship, B: their taxonomy tags, and C: their relevance to the topic or question at hand. Think about what will happen once the 'Let a book page appear in multiple books' patch lands in core, and the Fields In Core API system is finished.

I think that's what we're really talking about here. This idea of mine is just a halfassed way of getting something out of the software which it doesn't currently do, but it will soon. We must wait for the 'book page appear in multiple books' patch for D6, and eventually the Fields In Core patch for d7, before our docs could become this sexy.