Make help text at top of project usage overview page clearer/more helpful

-1 to the third paragraph, which is Drupal specific. Granted, at the moment drupal.org is quite possibly the only site using the update project usage module, but it would be possible for other sites running project* to write something roughly equivalent to the update_status module for their users that would get data to the project usage module.

I'd be cool with something like the following as the text returned by project_usage_help:

This page summarizes the usage of all projects on this site. For each week beginning on the given date the figures show the number of sites that reported they are using (any version of) the project.

Detailed usage information for each release of a project is available by clicking the project name. Only sites that have opted to allow usage information to be tracked are included.

Btw, note s/summarises/summarizes that I did. We should use the US English spellings here since the default Drupal language is US english.

Since this text comes from hook_help(), I'm guessing that we could override this in the drupal.org customizations module to include your last paragraph, which I do think would be good to have on drupal.org itself. So, in my opinion, I'd suggest you roll two patches: one for the project module with the first two paragraphs, and then one for the drupal.org customizations module that has all 3 paragraphs.

But maybe we want to wait until we come to a consensus as to whether the text should be changed or not.

-1 to your change in comment #1 as well. Not only is usage information for modules and themes displayed, but the Drupal project itself, as well as translations, installation profiles, and theme engines all have information displayed (I think).

Also, specifying modules and themes makes this text even more drupal.org specific, which as I said in comment #2 is, IMO, a bad idea.

You're right--in D6, you have to have the update status module enabled for d.o to get status information. The check box during installation controls whether or not the module is enabled or disabled once the site is installed.

As for overriding hook_help, my guess would be that a module that had a heavier weight in the system table that responded to the same page would thereby override text provided by another module on the same page with a lighter weight. I'm not sure if this is considered a best practice, however it's the only way, other than using the locale module, to alter the text produced in project_usage_help().

An alternative would be to make that text a configurable setting in the project usage module, so the administrator could override the text if desired.

This is good stuff. A few thoughts/clarifications:

A) I completely agree with aclight about putting the drupal.org specific help text in drupalorg.module, but improving the general help text as much as possible in project_usage.module.

B) hook_help() is cumulative. Anyone who's providing help for a given page just gets their stuff appended to whatever is there. So, {system}.weight just controls the order of the stuff you see on the page, not who's text clobbers everyone else's text. hook_help() isn't the most flexible system, but I think it's better than a setting (which would involve a bunch of text to unserialize on every page load on d.o).

C) Currently, drupalorg and project_usage are both at weight 0 in the system table on d.o. I'd be happy to bump the weight of drupalorg module to 1 to ensure it appended the final paragraph instead of prepending it (d < p alphabetically, so for now, drupalorg runs first). I can't imagine how that would break anything (he says, knowing full well it might -- d.o is cursed).

D) In D5, update_status.module only knows about modules since those are the only things with .info files. In D6, themes also have .info files, so update.module knows about those, too. Given how installation profiles work, there's no sense "checking for updates" for those, anyway, so I doubt that's ever going to happen. Usage stats for translations is tricky, especially as we move towards the translation server and the way that people get translations might be changing, too. So, for now, it's only showing modules, and in D6 and above, themes, too.

E) Early in D5 there was a setting in update_status to disable sending usage data when checking for updates, but that was removed as the module moved into core and before the official 5.x-2.0 release (before RC2, in fact). So yes, if you have update(_status) enabled, you're sending usage data, otherwise, you're not. See #153741: Add client-side support for collecting usage stats, #94154-61: update.module in core (formerly known as update_status) and #94154-62: update.module in core (formerly known as update_status) for some history on this if you care.

aclight's #2 looks good.

Suggested re-write for the third paragraph in #0:

Please note that these statistics are incomplete; only Drupal websites using the Update Status module are included in the data. As this module is now included with the download of Drupal since version 6.x, the data is heavily biased toward newer sites. More information on how these statistics are calculated

And have that link go off to the dww version that explains cron reporting, the history of update status, or whatever else you feel is relevant.

Until we have a whole separate page about how the usage stats work, we should just leave that link off. The closest we have already is http://drupal.org/handbook/modules/update but that's not really what we need. I think the rest of the improvements in here are worth doing now -- we can always build on them later if/when a nice handbook page exists that we can point to.

Again, let's make a separate handbook page with painstaking detail of all the various caveats to these statistics and link to it for the curious. This does not belong at the top of the page, pushing the content down below the fold.

I don't want to delay improving the help text until the handbook is written and edited. Here are patches for project_usage.module (using aclight's text from #2) and an initial patch for drupalorg.module using most of webchick's text from #7, along with a DB update to fix the system weight.

FYI: deployed on p.d.o and the update ran without trouble:
http://project.drupal.org/project/usage

Small change to dww's patch in #12 to change:

Detailed usage information for each release of a project is available by clicking the project name. Only sites that have opted to allow usage information to be tracked are included.

to

Detailed usage information for each release of a project is available by clicking the project name. Only sites that have opted to allow usage information to be tracked are included in these figures.

Committed #15 to HEAD and DRUPAL-5 of project/usage/project_usage.module. Rerolled #12 against drupalorg.module to include the link to the handbook page from #14.

Based on feedback from greggles and others in IRC, here are two new patches. One to further fix the changes to project_usage_help() I just committed (removes some duplicate text that's included in the drupalorg version, and uses variable_get('site_name') to customize it a bit), the other for improved (i.e. shorter) help text from drupalorg.module.

Committed and deployed: http://drupal.org/project/usage