I attach a patch with various fixes and improvements on the English for the user interface of the System module.

O Govinda
www.jswami.info

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Steven Jones’s picture

Guess this one needs a read through by as many people as possible, who know about grammatically correct English.

Will do that on the way back from work this eve, and get back to you.

---
Regards
Steven Jones

ChrisKennedy’s picture

This page lists all the actions available.
-> "This page lists all available actions." or "This page lists all the available actions."

This option makes Drupal turn out "clean" URLs
-> "Turn out" is unclear.

Ideally should be zero.
-> This should be a complete sentence.

If you're going to change short & medium date date formats you might as well convert all three into the same sentence construction.

CSS and JS bandwidth optimization.
-> It might be clearer to write out "JavaScript".

Finally, a longer description of the rationale behind this patch would be worthwhile, especially to describe some of the repeated changes. Many of the changes are stylistic modifications that are only subjective improvements.

Anonymous’s picture

Thank you, Chris, for going through the patch and commenting on it. To go through such patches is tedious work, and I'm grateful.

Your call for a longer description of the rationale for the patch is perfectly reasonable, so here we go.

Most of the changes are meant to address not mere matters of style but rather matters of grammar, punctuation, and clarity. The few changes in style, which I made because I thought them improvements, were rather a kind of "while we're at it" throw-in.

To get into specifics. . . .

  • The first change in the patch corrects a "dangling modifer," a common sort of fault often pointed out in basic grammar texts: "After completing the configuration form, the action will be available for use by Drupal." To get technical, the error occurs because the dependent clause ("After completing the configuration form") has no proper relationship with the subject of the main clause ("the action"). The action, after all, is not going to complete the configuration form. The patch corrects this error.

    ("'This page lists all the actions available" or "This page lists all the available actions"? Six for one, half a dozen for the other.)

  • The second change in the patch corrects an error in punctuation: a semicolon was being made to do the work of a dash. (That is, "this action; for example" should have been "this action--for example.")
  • The third change turns "Alternately" into "Alternatively." When we speak of offering a choice or alternative, "alternatively" is the preferred word. ("Alternately," though common, is often considered wrong, or at least less precise, and English editors will routinely change it.)
  • The fourth change fixes a mixed use of passive and active voice that makes the sentence confusing to read. ("Modules can automatically be temporarily disabled to reduce server load when your site becomes extremely busy by enabling the throttle.module and checking throttle." The sentence is a mess.)
  • The next change fixes a sentence in which overuse of the passive voice makes the sentence confusing. ("The auto-throttle functionality must be enabled. . . after having enabled the throttled mode.")
  • The next change again fixes an overuse of the passive: "It is important that update.php is run every time a module is updated to a newer version." It's run by whom? Updated by whom? By Drupal automatically? So: "Important: Every time you update a module to a newer version, be sure to run update.php." That's clear and definite, which is what documentation needs to be.
  • Next: I changed "It is useful to copy/paste this information when you need support" to "This information is useful to copy and paste when you need support." You can say this one is for "style." It's just better English.
  • The next change addresses a punctuation error and an error in logical categories. "Control how Drupal deals with errors including 403/404 errors as well as PHP error reporting." The modifier beginning with "including" is grammatically "nonrestrictive" and so must be preceded by a comma. And, logically, "PHP error reporting" is not among the "errors" to be dealt with; the errors are "PHP errors," not "PHP error reporting."
  • The next change fixes an inconsistency in the way the interface speaks to the user. The text for the other modules gives directions, using imperative verbs: "Choose," "Configure," "Tell Drupal." This one suddenly broke ranks and instead gave a description (and an over-long description too): "Settings for logging and alerts modules. Various modules can route. . ." I've turned this into a simple direction, like the rest of them: "Configure your logs and alerts."
  • The next change addresses what editors call a "noun pile-up": "CSS and JS bandwidth optimization options." (I agree with you, Chris, that writing out "JavaScript" would be clearer.)
  • Next: I turned "whether feeds should be titles/teasers/full-text" into "whether feeds should consist of titles only, titles and teasers, or full text." This makes clear that there are in fact three options and makes clear what those options are. (The second option was not "teasers only," as the text might have led us to believe.)
  • The next change addressed another instance of interface inconsistency, where the text again gave a description instead of issuing an imperative direction.
  • Next was a minor fix: "offline" (the dictionary spelling, matching "online") instead of "off-line."
  • Next: Replaced "'Choose which theme the administration pages should display in" with "Choose the theme for displaying your administration pages." I guess that's style. The former text is awkward.
  • Skipping over a few more fixes I made for awkwardness and grammar, we come to "This option makes Drupal turn out 'clean' URLs." (The former word was "emit," which in this context strikes me as a strangely formal word.) I think "turn out" is clear. It's a good sturdy English idiom. As defined in my Random House Dictionary: "to produce as the result of labor: She turned out four tapestries a year." Factories turn out cars, universities turn out graduates, and so on. If you really think it's unclear, though, I suppose we could say "produce" (not as good, I think, but okay).
  • Next: "URL," not "url."
  • Next: "When no other content matches" was wrong. It should be "no content matches"--that is, no content at all.
  • Next: "On a production server it is recommended that errors are only written to the error log." Grammar requires the subjunctive: "be only written." And again the passive voice makes things fuzzy. So: "Recommendations: On a production server, write errors only to the log." Clear, grammatical, and five words shorter.
  • The next one was for style: "causes Drupal to skip . . . This results in an additional performance boost. . ." Instead: "makes Drupal skip. . . This gives an extra performance boost. . . " More idiomatic, and saves three words.
  • The next was for clarity: "if you use aggressive caching and enable new modules, you will need to check this page again." When do I have to do that? Instead: "if you use aggressive caching, when you enable new modules you will need to check this page again." In other words: "When you enable a new module, check back here." I think that's clearer.
  • In the next change, the subject was a bit technical, and the English was just plain murky. The fix makes the matter clear.
  • The next change fixes multiple problems. The passive voice made unclear who does the enforcing. "Recreate" is better as "re-create" (to show we're not just having fun). And "users will not see new content for a longer period of time" was a puzzling way to say things. (Clear: "a longer period of time will elapse before users see new content.")
  • The next change made for clearer, simpler English.
  • Next: Changed "this setting should be enabled" to "you should enable this setting." Otherwise we don't know whether we have to do something or Drupal will do it automatically. I also fixed a error later in the text (elements in a series weren't parallel).
  • Next: A missing "the" and a missing comma.
  • Next: Another change to active voice: you are the doer, not Drupal. Reworded the last sentence to make it clearer (instead of fixing its multiple errors in punctuation).
  • Next, fixed a confusing mismatch between what the users see and what the interface tells them. The message says, "Global setting for the length of XML feed items that are output by default." And the user's options are "Titles only," "Titles plus teaser," and "Full text." I changed that wordy and confusing message to "What to include in XML feeds."
  • Next: a small fix in wording.
  • Next: "When enabled, users. . ." was a dangling modifer. ("Users" are not enabled.)
  • Next: The copy about the date display. Gosh, I no longer know where in the interface that text is supposed to appear. (If I could find it, I suppose I'd agree that, as you say, the descriptions would best all be the same way.)
  • Next: Fixed two dangling modifiers: "When set to 'Online,' all visitors. . ." (Visitors are not set to "online.") The second dangling modifier is of the same nature.
  • Next: Changed "consequently" to "and so." (I prefer short words.)
  • Next: Deleted three needless instances of "that." (I think "Ideally should be zero" is okay. Though it's a sentence fragment, it's meaning is clear, so I saw no need for a change.)
  • Next: Appositives should be set off by commas.
  • Last: Added a comma.

I'm in a sort of predicament here. If I'm going to write more such patches, documenting them at this length would get mighty tedious. Fixing text is something I can do fast, as a diversion when I need a break from heavier work. But documenting them this way. . . . that's another story.

I've done professional editing for some thirty-five years. I've edited a monthly magazine, dozens of full-length books, and of course the usual brochures, newsletters, fund-raising letters, and so on. I've taught seminars on editing. And among my most recent editorial projects was a 3-volume scholarly translation and commentary of a medieval Sanskrit work, amounting to some 2,800 pages.

In short: When it comes to English, I know what I'm doing. And I can make a decent contribution here. But I think what's going to have to happen is that someone "up there" in the Drupal hierarchy is going to have to decide to just trust me.

I know that may sound high-handed or immodest. But I think it's realistic.

Yes, I can make mistakes. And where I most need others watching after to me is to make sure I haven't misunderstood something technical about Drupal itself, or introduced an error in coding.

But as for my English--it's good enough that if I edit some text in the Drupal interface the English will be better, not worse. And probably a lot better.

Chris, I understand that this predicament isn't one created by you. And again I'm grateful: You actually took the trouble to go through the whole patch! Now I think we need to hear from "the people who make the decisions."

Thank you again, Chris. And all the best.

Cordially,
O Govinda
www.jswami.info

webchick’s picture

Component: system.module » documentation

Adding to shiny new documentation component!

Will try and review this later.

ChrisKennedy’s picture

@O Govinda: I did not ask for a line by line description of every change. I asked for a longer description than the one given, which added no information to the title of this issue issue "english fixes." You need to be reasonable here: a 30k patch needs more than one unhelpful line of description. Things like: giving examples, providing change counts by type, and summarizing routine errors. This is standard practice.

I'm in a sort of predicament here. If I'm going to write more such patches, documenting them at this length would get mighty tedious. Fixing text is something I can do fast, as a diversion when I need a break from heavier work. But documenting them this way. . . . that's another story.

Wrong, false dichotomy. I never asked for a line-by-line description, nor did I want one. Use your editing skills to write a concise summary next time.

I've done professional editing for some thirty-five years....

That's great - save it for your resume. Experience and/or expertise does not guarantee perfection, nor does it give you cart blanche right to change whichever strings you see fit without any discussion.

Now I think we need to hear from "the people who make the decisions."

This is open source - we make the decisions. The core committers do not need to comment on this issue until it is RTBC, which I, webchick, or anyone else can do. They are very likely to trust any string decision made in this thread as long as it was adequately vetted, which is what I am trying to do.

Regarding the strings: I would prefer "produce" to "turn out". I know the meaning of "turn out" - quoting a dictionary is unnecessary and rude, frankly. Where I am from (Austin, Texas and Washington, DC) "turn out" in this context is uncommon and unclear.

Anonymous’s picture

Thank you for the response, Chris. I accept your chastisements.

Thanks also for the instruction on standard practice. Standard practice in open-source documentation is not something I'm well acquainted with. (I suppose you've already figured that.)

I never asked for a line-by-line description, nor did I want one. Use your editing skills to write a concise summary next time.

Understood.

That's great - save it for your resume. Ouch!

Experience and/or expertise does not guarantee perfection (My text acknowledged that), nor does it give you cart blanche right to change whichever strings you see fit without any discussion. Fair enough.

The core committers. . . are very likely to trust any string decision made in this thread as long as it was adequately vetted, which is what I am trying to do.

Appreciated. Again, I'm not well acquainted with the protocols and procedures here.

Regarding the strings: I would prefer "produce" to "turn out". I know the meaning of "turn out" - quoting a dictionary is unnecessary and rude, frankly. Where I am from (Austin, Texas and Washington, DC) "turn out" in this context is uncommon and unclear.

Sorry if I came off rude or condescending. Your comment--"unclear"--was unclear to me. And so that quote from the dictionary. (Where I come from, when other editors question a word or phrase, that's the first thing we do: check the dictionary. And we consider citing it to be within the realm of good manners.)

Truth be told, I'm still perplexed as to why "turn out" would be unclear (and I grew up only a few hours by car from DC). But, as I said, if you'd prefer "produce" that's fine with me.

Thanks again.

Cordially,
O Govinda
www.jswami.info

PS: Oh, webchick, I love that shiny new documentation component! Thanks.

Anonymous’s picture

Category: task » bug
Freso’s picture

Status: Needs review » Needs work

O Govinda:
Now that you and Chris have talked a bit back and forth, do you think you could reroll the patch, incorporating what you've discussed so far? Or do you now feel that anything need to change?

For the record, as a fluent but non-native English speaking Dane, I'd have to say that "produce" is more clear than "turn out". "Turn out" sounds to me like something dialectical, whereas "produce" is simpler/more natural – or at least is closer to generic Indo-European languages for the same thing. :)

Anonymous’s picture

Status: Needs work » Needs review
FileSize
29.59 KB

Thank you, Freso.

I'm not experienced in rolling and re-rolling patches. What I've done here is taken the patch, used a text editor to make slight changes to the revised English text, and then saved the patch as "r1." I hope this is all right.

Here are the changes (with explanations):

  • actions available --> available actions

    (As suggested by Chris.)

  • turn out --> produce

    (As suggested by you and Chris.)

  • set options for CSS and JS bandwidth optimization --> set options for optimizing bandwidth for CSS and JavaScript.

    (Chris suggested spelling out "JavaScript." And I've further broken down the noun pileup.)

Though Chris comments that "Ideally should be zero" should be made a complete sentence, to me it looks fine as is. It's what the module has, and I haven't changed it.

By the way (just for academic interest):

"Turn out" is idiomatic rather than dialectical.

Attesting to the use of "turn out" to mean "to produce (usually implying rapidity, facility, or skill)," the Oxford English Dictionary cites examples going back at least as far as 1878. For example, "No place. . . could. . . turn out more splendid ships' figure-heads" (1878). And: "La Touche. . . is one of the best half-backs Sedbergh has ever turned out" (1913).

But I accept that "produce" is likely to be simpler for translators. And that's a good enough reason to use it.

Thanks again, Freso.

Cordially,
O Govinda
www.jswami.info

catch’s picture

Status: Needs review » Needs work

This option can interfere with module development. Recommendation: Turn this on only when your site is complete.

This is in double quotes, doesn't need to be. Also "Recommendation: Turn this on". No capital required after the colon, and I think it could be worded better than this. Don't have alternative wording at the moment though but maring to needs work.

Anonymous’s picture

Lower-case “t” is fine. “Could be better worded”--we need more help. What aspect of the wording would you like to see improved?

O Govinda
www.jswami.info

catch’s picture

Bit more awake now.

"This setting can interfere with module development and its use is not recommended until your site is in production."

How's that?

Anonymous’s picture

I think that having two short sentences--one idea per sentence--gets across faster. And a brisk command--"Recommendation: Do this"--is more clear and definite than the passive-voiced "is recommended."

Also, "in production" seems like Drupal insider jargon. We understand it to mean that your site has "gone live." But non-techies could easily misunderstand it to mean "under development" (the opposite of what we mean).

Of course, a site is never "complete," so that word can be confusing too. Should we say "until your site has gone live"? Or "until your site is up and running"?

catch’s picture

I'd say "until your site has gone live" is much better.

Anonymous’s picture

". . . until your site has gone live."

Fine.

keith.smith’s picture

Status: Needs work » Needs review
FileSize
8.21 KB

There's a lot of stuff here!

However, much of it now outdated due to changes since this issue was submitted -- new features have been added that have substantially impacted some of these old text strings, including some actions (triggers) modifications, custom date/time formats, etc.

Additionally, some of these items have already been addressed by recent, smaller patches to user-facing text.

I went through the original patch and cherry-picked out several of the changes that still applied, found a few other instances of text that could use a bit of tweaking, and have included these items in the attached patch for review.

(Note that I did not include several proposed changes only because I know that there are still pending patches in the documentation queue that directly address them.)

keith.smith’s picture

FileSize
21.81 KB

I realized after a patch for installer task descriptions earlier today, that "Setup" vs. "Set up" may be a more pervasive problem. So, I went through all the instances of "Setup" and "setup", and changed them if necessary, and rolled these changes into this kitchen sink style patch.

Freso’s picture

Status: Needs review » Needs work

AFAIK/CT, The setup of languages and translations is completely web based. should remain "setup" (and thus not get changed into "set up"), as it is indeed referenced as a noun ("a setup") here and not as a verb ("to set up").

There are a few '#description' => t("..."), where the text in t("...") doesn't contain any apostrophes or characters that need to be parsed – they should be quoted in apostrophes. (Also, there are a few '...' => t(...) that doesn't end with a comma, even if the coding guidelines clearly state they should.)

The user module supports user roles which can set up fine grained permissions [...] sound a bit awkward. How about something akin to The user module supports user roles which can be used to set up fine grained permissions, allowing each role to do only [...]? I'm sure y'all are able to come up with something better, but the current text (with or without the patch) isn't good.

keith.smith’s picture

Title: English fixes for System module » English fixes for System module, and other miscellaneous corrections.
Status: Needs work » Needs review
FileSize
25.52 KB

Oops. Yep, I zoned out on a few of these. Thanks for reviewing, Freso.

I *believe* I addressed the issues you raised, plus corrected a typo the earlier patch would have introduced.

Since this is a kitchen-sink of grammatical junk, I also expanded the issue title, and have added some it's and its fixes.

Please review!

keith.smith’s picture

Title: English fixes for System module, and other miscellaneous corrections. » Minor spelling issues: it's / its and setup / set up, and misc. system module strings
FileSize
25.6 KB

Rerolling to remove a bit of fuzz.

Retitling to more appropriately reflect this issue.

This patch will conflict with the one in http://drupal.org/node/175876 ; whichever one (if either) makes it in, I'll reroll the other.

Note that this patch now basically contains spelling error cleanup, mostly it's / its and set up / setup confusion.

keith.smith’s picture

Title: Minor spelling issues: it's / its and setup / set up, and misc. system module strings » Minor spelling issues, spacing changes, and misc. system module strings
FileSize
49.65 KB

I encountered several double spaces between sentences here and there, and decided to roll them into this patch, which has now officially gotten about too big to realistically review (so I'm going to try to not poke more stuff in here).

Note that the block module help text touched by this patch (eliminating some double spaces between sentences) should likely now be expanded with information about the drag-and-drop interface enhancements. There is another patch in the documentation component queue that is directly related to block module help text, so I'd probably prefer to just let this clean up the space and make substantive changes to the help text in the other issue.

So to recap, this kitchen sink patch now has:
-- some few system module strings coming over from this issue's origin
-- numerous changes adjusting "set up" and "setup"
-- numerous changes adjusting "its" and "it's"
-- numerous changes adjusting double spaces between sentences

keith.smith’s picture

Status: Needs review » Needs work

This will need rerolling due to the commit of the patch in http://drupal.org/node/175876.

I'll do this tomorrow. Setting to CNW temporarily.

keith.smith’s picture

Status: Needs work » Needs review
FileSize
49.76 KB

Rerolled after two hunks failed due to recent commits.

Dries’s picture

Status: Needs review » Fixed

Wow, this is great work. Thanks for the detailed issue comments. That helps. Committed to CVS HEAD!

Anonymous’s picture

Status: Fixed » Closed (fixed)

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

InfinityMark’s picture

Ignore this post...