Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
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.
Comment | File | Size | Author |
---|---|---|---|
#10 | statistics_help-4.patch | 8.21 KB | keith.smith |
#8 | statistics_help-3.patch | 7.61 KB | keith.smith |
#6 | statistics_help-2.patch | 7.61 KB | keith.smith |
#5 | statistics_help.patch | 7.61 KB | keith.smith |
Comments
Comment #1
sepeck CreditAttribution: sepeck commentedMoving to documentation and changing to normal as nothing is actually broken.
Suggested update text welcome.
Comment #2
oadaeh CreditAttribution: oadaeh commentedIf 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.
Comment #3
add1sun CreditAttribution: add1sun commentedCleaned it up and clarified a bit. If folks have more to add, feel free.
Comment #4
webchickSomeone 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.
Comment #5
keith.smith CreditAttribution: keith.smith commentedFurther 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.
Comment #6
keith.smith CreditAttribution: keith.smith commented*sigh*.
I had a "show display" in there. Blargh. I shouldn't do this when I'm tired.
Comment #7
Gábor HojtsyThe 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.
Comment #8
keith.smith CreditAttribution: keith.smith commentedI 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.
Comment #9
keith.smith CreditAttribution: keith.smith commentedArgh. My cron language needs work in this patch as well.
Temporarily setting to CNW until I roll a new patch.
Comment #10
keith.smith CreditAttribution: keith.smith commentedHere 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.
Comment #11
Gábor HojtsyThe style looks good to me, just as the content, so committed. Thanks for your continued great work!
Comment #12
(not verified) CreditAttribution: commentedAutomatically closed -- issue fixed for two weeks with no activity.