Display 'last modified' date on Drupal handbook pages

I agree with this. Some of the pages are ancient, and not everything has been tagged with the appropriate Drupal version.

Problems include misleading last modified dates... maybe all that happened was it moved, or was tagged, the actual content did not change.

Anisa.

+1

Looking at handbooks is rather cumbersome because the first thing I have to find out is if it's still relevant. There are handbooks that show deprecated ways of doing things or haven't been updated in a long time.

Maybe we can archive some of the pages that are deprecated or rework the documentation so that information can be shown as deprecated, current or leaning to future methods of doing something.

Why hasn't this even been implemented though. Seems to me that adding a simple one line code snippet to theme in the information would be a rather easy fix for this. Is there some kind of anti-last modification movement?*

*end sarcasm

Thanks!

You could start by posting that snippit here.

This is a good idea and likely to be implemented IMO.

I am not a programmer, but I am sure I can hunt around some drupal themes to find the snippet.

I would obviously have to be changed a little. While I can administer a Drupal site, I can't program on it (Yet!?).

Let me do some digging and see what I can find.

Also note that the last updated date is listed under the revisions tab. There was a recent back and forth about not making that (revisions tab) available to anon users. That sprang frm a discussion about listing the people who have contributed to a page, which was nixed since some people want that and others don't.

There is an Archive book now where docs team members can move deprecated content. Just make an issue in the docs queue to get it moved as you find it. My only concern about the last updated date, is that is doesn't necessarily tell you if it is still relevant or not. The version tag is much more indicative. There are lots of old pages that are still completely relevant, moreso than more recently written pages. The last updated date makes more sense when viewed in the context of the full revision info.

So, I'm not horribly opposed to it, I just feel like it isn't actually as useful as people think it is.

Granted, It won't be a catch-all to find out if information is relevant or not. I just think it would be an added tool to help users locate needed information.

I do think their needs to be better way to organize documentation within drupal and the version tags are helpful in doing some of it. I just think some more brainstorming can be used to organize the data better.

Definitely agree on the organization. Many people are kicking ideas around and the d.o reorg that it is underway will have a significant impact on docs organization, so these things will be addressed. I just don't think the date a page was last modified does much for us in that direction.

I just don't think the date a page was last modified does much for us in that direction.

I agree with that. To take one more-or-less random page as an example: This one just showed up in my tracker as edited today, but that was just a minor typo correction. In June, a new module was added to the list of reviews, but the last time any of the other entries was edited was in March. And there's nothing in the log notes that indicates that anyone has done a review of all the reviews at any time since the page was created, in January.

So, some of those editors may well have been improved significantly since the January, and and "Edited 7th August 2008" notice would be quite misleading.

However, especially for reviews of contrib modules, it might be useful to have manually updated notices (simply written into the text) about the time they were last updated. That could be something to add as a recommendation to the docs handbook.

I think knowing the last time a page has been updated is an important piece of information to help find out if an article is relevant or not. Like I said, its not a end all-be all to the solution, but could be useful to decipher when a piece of content was last touched. It could also be used to search for content that hasn't been updated in a while and see if it is still relevant, if not it could be updated by the documentation team.

I would like to see a 'wiki' style for the handbooks. Instead of creating 'books' we could create pages that would automatically link to one another based on the text within the context. I think we can look to Wikipedia or Wikia for inspiration to help find a way to traverse all the knowledge on d.o.

The wiki discussion has happened over and over (lots of forum posts and mailing list archives on this) and generally the consensus is that handbooks are better organized in a hierarchy rather than being randomly linked together. Regardless, that's not what this issue is about so I'll stay on topic.

Again, I do want to point out that the last modified date is already available under the revisions tab, which can also give more context than just a date. Printing the date on the face of the page itself doesn't do anything to help us *organize* content and may not be a good indicator at all about the relevance of the content itself. I remain neutral on adding the cosmetic change.

If we want to create a list of "not updated in a long time" pages, that is info we already have available in the db so a custom page, similar to the recent updates and handbook comments pages can be created with a patch to the drupalorg.module. I'd be interested in exploring that but that would be a new issue, aside from this one.

The wiki style was just me brainstorming.

I realize that the dates is on the revisions tab. What I am talking about is the the most recent date being shown on the node itself so users don't have to do any excessive clicking. If I look for 10 handbook pages that's 10 searches + 10 page views and another 10 to find when it was updated. So roughly (give or take a few pages) I have to search 30 or so pages to find information.

Honestly, I don't see why we are debating this back and forth. Most content on the web has a 'created' or 'updated' date shown to the user (mostly near the title or headline). Even the tracker tells us when new comments have been posted. To the best of my knowledge, this doesn't seem like it would create a lot of overhead for d.o or make the templates overly complex.

Granted, it might not be the best solution, or useful in every case. Some pages that are 4 years old are still meaningful and useful while pages 6 months old are pointless and unneeded. but at least it is something. Maybe someone can go through the handbooks and clean out all the older handbooks or maybe unpublish them. I find out dated material more for contrib modules than for core. Maybe a tag can separate the core handbooks from the contrib module books.

I do agree that we need a new system to organize handbooks for d.o. I am not talking about a major overhaul of the system. Just a simple 'print last updated' snippet into the theme will do. I am not a programmer so I cant provide the code. I am still learning PHP then I will work on learning the Drupal API.

Some pages that are 4 years old are still meaningful and useful while pages 6 months old are pointless and unneeded. but at least it is something.

Well, that's my only objection: It is "something" that may be directly misleading. To go back to the example page I mentioned: That page tells me that the YUI Editor is still in dev version and doesn't produce valid HTML. If the page has a "Last updated 7th August 2008", the reader will assume that the contents of the review was checked at that date. But looking at the project page, we find that the module has had lots of revisions since then, and that the review may well be very, very outdated.

To the best of my knowledge, this doesn't seem like it would create a lot of overhead for d.o or make the templates overly complex.

To the best of my knowledge, you're right about that. But I don't think I've seen anyone make those objections.

Thank you courtney for the snippet. I am no developer and I am still learning PHP, but this code seems rather easy to decipher and verify.

In an effort to get this implemented I am marking this issue 'code needs review'.

To zirvap,

I understand your points and they are valid, but personally I think this code will be helpful to drupal users and be more consistent with the rest of the site. Forums, issues and main articles have dates clearly laid out on the main node page, so to be fair this code would only make the site more consistent.

To make a point regarding your YUI editor comments. Granted this could be misleading, but information is not inside a vacuum. Admins and developers should take all data from d.o and make a decision about it. The fact the the editor is in a 'dev' state, in my opinion, would raise a flag immediately. The 'updated' date would take a lower priority when making my decision to use that module.

Since this is a d.o theming request, I'm moving to the proper queue.

I'm fine with this moving forward, tho I have no direct access to the theme changes needed. We may also want to point this out in the greater d.o redesign that has kicked off since Drupalcon Szeged a few weeks ago.

Slightly off-topic but related to this discussion, for those that are interested, I also wanted to point out that there is also an issue to add a new vocabulary that has an "outdated" term in it #304826: Define documentation vocabulary. That way we can explicitly mark pages that need an update and create a view of those pages.

this should be a 30 sec change in the UI - who has access to this?

Done.

Reopened. Displays the author of the last revision. Is this what we want?

I am perfectly fine with the last modified author showing on the page. If people are really adamant about it maybe this would work:

Created by: Author Last Modified By: New Author on 1/1/01

I realize this might be feature creep, but I am only suggesting it if people oppose the current setup.

No, please do *not* put the author name. There was a looong discussion about this in other issues that I d don't have time to find right now, and there are a number of people who do not want their name prominently associated with pages. Just because I copied a comment into a new page (which makes me the "author") or I fixed a typo (which makes me the "new author") does not mean I want support requests about the page.

Well would a simple "Last Modified: Date" work?

Maybe "Created: 1/1/01 Last Modified:1/2/01"

Suggestions?

Right - we just need a trivial modification to the node template for books nodes to show just the date. The frustrating thing here is finding one of the few people with access to change the theme code.

I'd be happy to do it, but the last I heard, the theme is no longer maintained where it used to be (the private CVS repo). There's now (I think) an SVN repo for it, but there's no documentation on how infra maintainers are supposed to access this SVN repo. :( There's no post on infra.d.o about it, there's been no infra issue about it, and AFAIK, there was never a thread on infra@d.o about it (just a message I can't link to announcing the change which was lacking any details).

Furthermore, I just tried to hack this into my local copy of bluebeach, and ran into some unexpected behavior in node.tpl.php:

 <div class="info<?php print ($page == 0) ? '-list' : '-page'; ?>"><?php print substr(str_replace(array(' on ', 'Submitted by '), array(' - ', ''), $submitted), 0, -1); ?></div>

So, when I tried to add this to template.php inside the 'node' case for _phptemplate_variables():

  if ($type == 'book') {
    $variables['submitted'] = t('Last modified: !date', array('!date' => format_date($variables['node']->changed, 'custom', 'j F, Y')));
  }

The resulting output on a handbook page gets truncated:
Last modified: 2 August, 200

The substr(str_replace(...)) is to change the formatting of the "Submitted by dww on Thu, 09/18/2008 - 00:21." default from core into just "dww - Thu, 09/18/2008 - 00:21". str_replace() doesn't hurt us, but the substr() always truncates the final character. Seems like a weird place to be doing that string manipulation, but I'm not a themer. If you add a bogus '.' on the end of the date when setting it in template.php, it starts working again. Thanks, bluebeach.

Attached is therefore the patch that seems to do what we want. Any complaints with the approach in this patch are welcome.

Looking on the shell, it appears that although there was talk of the SVN repo mentioned above, d.o itself is still running a copy checked out from the private CVS repo. So, I suppose I have a few options:

A) I could just commit this patch to the private repo, deploy it on d.o, and let the folks secretly dealing with the SVN repo figure it out.

B) I could just locally apply it on d.o for now, and leave the private repo alone.

Input on which of those options I should act on is welcome, too.

Here's a potentially better patch that doesn't try to just reuse the $submitted variable. It sets up a $modified variable in template.php and displays it (without weird string manipulation) in node.tpl.php, using the same "info-page" div class for the CSS, but also a "modified" class in case we'd like to further tweak it.

Also, in case you're not following the infra issue queue closely, I posted #317093: Document how to access the d.o theme SVN repo to try to figure out what we're supposed to do with stuff like this.

why not copy the node.tpl.php to node-book and then format and print the date there?

If you can post or email the existing node tpl file, I'd be happy to do it.

Continue using CVS until SVN works. I plan on doing some basic cleanup once SVN starts working well, and we will have more people able to make and test patches.

@pwolanin #26: "why not copy the node.tpl.php to node-book and then format and print the date there?"

I guess it depends on how likely it is that a) we'd want to see last modified on other node types and b) there will be other ways that the handbook layout/formatting will diverge from other node types. Seems better not to fork the entire file just for this change, since then there will be two separate .tpl files to update if/when we need to tweak anything else. Plus, if we want to see Last modified on anything else, it'll become a few byte change to that 'node' case in template.php. My basic "code reuse is important" instinct as a developer shining through... But, if folks think a separate node-book.tpl.php is preferable, that's ok, too.

For example, it *might* be worth having "Last modified: ..." on project nodes, too. That's about the only other node type currently on d.o that people semi-regularly edit and where it might be useful to know.

I tend to agree with dww that here is no need to dupe the node template for this change. My pref would be to use the new variable.

One (hopefully last) minor tweak to #25 for more consistency: instead of using a custom format, just use the default medium format, which is what the usual creation date is rendered as.

@drumm: Thanks for the info on committing directly to CVS. I assume you're not opposed to this change since you didn't otherwise say anything about my patches. ;) However, if you wanted to explicitly give this the RTBC treatment, that'd be lovely, seeing as how you're the official bluebeach maintainer now. Thanks...

Code looks okay. I haven't read all 31 comments here, so I will assume it fulfills what is needed. Bonus points if you commit this to HEAD too.

Committed to DRUPAL-5 and deployed on d.o, for example: http://drupal.org/getting-started

@drumm: "Bonus points if you commit this to HEAD too."

I tried, I really did. First I ran dos2unix on all the bluebeach files in HEAD so that the patch had a prayer of applying. I did commit that much, at least.

However, the patch still failed in template.php, since there's no _phptemplate_variables() at all. :( So, porting this patch to HEAD was going to take significantly more effort than I can spare right now. Seems like we need a more thorough-going sync to HEAD before such "please commit to HEAD, too" requests can be reasonably fulfilled. Sorry.

I'm not even sure what happened in HEAD since the DRUPAL-5 branch was created. Any reason not to just take all the latest files from the end of DRUPAL-5 and commit them to HEAD? I guess I could do that CVS archeology, too, but this isn't really my main itch these days. I was just trying to be helpful with what I initially thought was going to take 5 minutes -- I now find myself feeling roped in to a much larger task. So, being honest, I'm unassigning myself and setting this to "to be ported".

Sorry/thanks,
-Derek

Side note: see #317193: Front page case studies: favor forum posts over book pages about an unintended side effect of this change.

HEAD is 6.x code.

@drumm: Ok, duly noted. Let's leave this issue alone for now, and first deal with #317341: Sync DRUPAL-5 and HEAD branches of bluebeach as its own task, instead of confusing this thread with that discussion. Thanks.

Whoops, I guess I committed/deployed my copy of template.php that included project nodes for "Last modified:" behavior, too. ;) See any project node, e.g. http://drupal.org/project/infrastructure. Is that what we want? I can see both sides of this one:

pro: Project nodes are semi-regularly edited by their maintainers, so it might be useful to see that info.

con: A lack of the project node itself being updated isn't an indication that the project isn't being actively maintained. New releases, CVS commits, issue replies, etc, don't touch the project node, so that's not really a good indicator of project activity.

I'd be happy to take those ~30 bytes back out of template.php if we decide the con outweighs the pro, but I thought I'd ask first.

Cheers,
-Derek

That looks kind of funny to me - I'd prefer to just have it for book nodes right now.

Yeah, I agree. Done.

Guess I'm too late. I would have voted to keep it. I happened to see it on my project page and thought it was kind of nice. I put a lot of info on my pages and it's handy for people to see at a quick glance if there's something new in all that. LOL

Michelle

@Michelle: If you want it, probably best to just start a separate issue to enable it for project nodes (linking to/from here). It's trivial to put it back if there's more support than opposition...

Man, I am thrilled that one of my issues actually got implemented.

Can we mark this as 'fixed' or 'closed'?

@specmav: Not until #317341: Sync DRUPAL-5 and HEAD branches of bluebeach is done and we can commit this to the HEAD branch of the bluebeach theme in the private CVS repository. I can relate to your desire to clean this out and see something "fixed", but we really need to keep track of the state of this feature so we don't forget there's still work to do. Sadly, there's only about 3 people on Earth who can complete the remaining steps here...

Sure, no problem!

Who are the three people? Dries, you and God?

*whoops, got carried away!*

This is already in the 6.x branch.