http://drupal.org/handbook/modules/statistics/ needs work. It is confusing, it doesn't clearly tell us how to turn on and use the statistics module, the text doesn't make it clear which words refer to some setting or page or option within Drupal (use boldface to tell us what refers to a specific link or page within Drupal), and it doesn't tell us how to get to these options or pages, or at least where it does, it stuffed at the bottom, away from the stuff it supposedly describes.

Marking as critical since 1. this page is so bad and 2. it's about a core module.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

sepeck’s picture

Title: http://drupal.org/handbook/modules/statistics/ is awful » Statistics help page needs update
Project: Drupal.org site moderators » Documentation
Component: Textual improvements » Admin Guide
Priority: Critical » Normal

Moving to documentation and changing to normal as nothing is actually broken.

Suggested update text welcome.

oadaeh’s picture

If you click on the 'Add new comment' link, you can type in the text you think should be there, including the entire re-worked content.

add1sun’s picture

Status: Active » Fixed

Cleaned it up and clarified a bit. If folks have more to add, feel free.

webchick’s picture

Project: Documentation » Drupal core
Version: » 6.x-dev
Component: Admin Guide » documentation
Status: Fixed » Active

Someone needs to roll a core patch so that the help text in statistics module reflects what's in the handbook page. Note that the help also needs to match that of other core modules which on a quick glance looks like the handbook page might need some tweaking. Eventually, the handbook page and what's shipped with 6.x should be identical.

keith.smith’s picture

Status: Active » Needs review
FileSize
7.61 KB

Further clean up of the statistics module help. Some of the option names didn't match the help text, etc.

If a version of this patch is accepted for core, I'll edit the Statistics handbook page to match.

keith.smith’s picture

FileSize
7.61 KB

*sigh*.

I had a "show display" in there. Blargh. I shouldn't do this when I'm tired.

Gábor Hojtsy’s picture

The new text looks very good, and is a great improvement in its current broken up state for translators. Some notes:

- as hass noted on the locale patch, we avoid backslashes in strings, so where ' is needed, feel free to enclose the string in ", but if you need both, feel free to keep ' as a wrapper, as often you need more " then ' inside
- we try to stay away from capitalized stuff inside sentences... I am not sure whether I should suggest you lowercasing everthing in the text as it makes for some lost meaning along the way... however, at least there is some inconsistency with how things are used here. "Permissions page" is uppercased, and includes the "page" in the link, while "blocks configuration page" is not uppercased, and does not include the "page" word in the link.

keith.smith’s picture

FileSize
7.61 KB

I had about five minutes to kill before waiting for a meeting, and so, checked this out.

Thank you for your comments and review.

I modified one string that was delimited with ' but also included a \' (and did not otherwise include " like in a tag). In a cursory examination, that was the only string that I thought I could easily change to " to eliminate the \'.

On the capitalization, I agree with what you're saying, and I admit to perhaps not being as consistent on this point as I should have been. I think my intent, though, was to capitalize the words that matched text in the menu, like Top referrers, even if it occurred in the middle of a sentence. Additionally, things that refer to instances of that exact text in core -- say in a menu item, or caption to a fieldset, or description for a text field -- should be italicized or be a link, so as to set their status apart from normal text. Now, that said, I haven't reviewed this extensively to make sure that I was internally consistent on this point.

keith.smith’s picture

Status: Needs review » Needs work

Argh. My cron language needs work in this patch as well.

Temporarily setting to CNW until I roll a new patch.

keith.smith’s picture

Status: Needs work » Needs review
FileSize
8.21 KB

Here is a version with the correct "cron maintenance task" language and the links uncapitalized.

The convention in this patch is:

- if a link to a menu item occurs mid-sentence, do not capitalize the link text
- When referring to a textfield description or the title of a particular block (or some other object that is not linked to, but is a discrete identifiable piece of text found on another Drupal page, capitalize as found in the Drupal interface and italicize.

As in:

When the Enable access log setting ...

or

The Discard access logs older than setting on the access log settings page

Also: include "page" in the link, when appropriate as in "access log settings page" or "statistics page".

If we sorta halfway agree on a convention here -- even if it is not the one I outline here -- I'll take a look through the other help texts that I've done and do a quick followup patch that standardizes them where necessary.

Gábor Hojtsy’s picture

Status: Needs review » Fixed

The style looks good to me, just as the content, so committed. Thanks for your continued great work!

Anonymous’s picture

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.