Interface text for contact form -- fogginess in the text

Updated to 5.x-dev.

Moving to documentation component.

This one should be simple -- just swapping a "setup", which should be "set up", into a "configure".

Another good catch.

I kind of agree with O Govinda here that category does not seem to be the right term to use here. What about renaming them to "contact groups" or something along these lines?

Yes, it likely needs further work in that regard. Category is somewhat overloaded here.

How about something like this, which changes category in the user-facing text to "contact group".

Note that this patch does not change the internals, which still refer to category for these values in bunches of places. Er, I can change them too -- or at least I think I can, with help probably -- to be consistent if that would be A Good Thing(tm).

If we change the terminology, we should also change the internals.

I agree that "site-wide" is bad terminology, also "Contact us", it should probably be written Contact us or 'Contact us' in the help text to show it's an example.

OK, keep "category". (Although I am not sure it is the best choice, I am not a native English speaker).

Setting back to needs work - for "Contact us" contact us instead of "site-wide", and for reverting to categories since that seems to be the consensus so far.

edit: thanks Gabor for spotting the typo, corrected it.

You mean reverting to "categories" from "groups", I guess.

So "contact groups" was turned down, so what about getting back to the initial issues and solving those?

The pressing thing (incorrect use of "setup") from my patch in #4 has already been fixed.

There's a lot of discussion here about the use of "site-wide". This usage doesn't bother me really, but I can see why it is not optimal. I'll try to roll a patch in the next day or so.

RE:Terms

My only problem with "site-wide contact form" is that "site-wide" is unnecessary. A "*Personal* contact form" requires that addition clarification. Where as a "contact form" is a "contact form". If you took "site-wide" literally, you'd understand it to be on every page.

Really, the terminology should simply be "Contact page". There are not multiple contact pages, and I don't believe the form can live outside of that page by default.

As for "categories", I think the simpler, more generic "title => group of recipients" terminology would suffice.

Now category is no longer used to describe anything the taxonomy module does (within Drupal anyway) it's slightly less confusing in this context.

I still reckon the main improvement here would be "Contact us".

Indeed, "contact us" sounds better.

Ok this just changes it to Contact us from "site-wide contact form". I tried to standardise it everywhere I found it, including the code comments. Would be good to get some eyes on the wording - there's a few places where calling it "Contact us" felt a bit awkward. Leaving as needs work since if we agree on the wording this still needs a permissions change and upgrade path for that.

Just as a note, I think this will conflict with http://drupal.org/node/197297 -- which isn't a problem, I'm just adding this to remind myself to do rerolls upon either commit... I think the only thing in that patch was dropping the "thereby" or something similar.

+      $output = '<p>'. t('The contact module enables a <em>Contact us</em> form, and the use of personal contact forms for users, thereby facilitating easy communication within the community. Personal contact forms allow users to contact each other by e-mail. The <em>Contact us</em> from allows users to contact the site administration from a central location. Users can specify a subject and message in the contact form, and also request that a copy of the e-mail be sent to their own address.') .'</p>';

"...and the use of personal contact forms for users" sounds odd. And, while we're here, can we lose the "thereby" in this too, since its unnecessary. "The Contact Us from" should be "form" maybe?

On a very quick run-through, the rest of this looks basically fine to me! Thanks catch! I know this wasn't up for review, but I was here anyway... :)

and the use of personal contact forms for users" sounds odd

Yeah that's the bit I had trouble with. Because "Contact us" has the word 'contact' in it, it's harder to combine "site-wide and personal" in those sentences. Might required a ground-up rewrite of those sections rather than hacking at what's there to make it work.

Text looks good, but can you really have more than one "Contact us" form? I thought it was just categories..

Thanks for working on this!

+ $output = '<p>'. t('The contact module lets you post a <em>Contact us</em> form and also gives each user a personal contact form, for easy communications. The <em>Contact us</em> form lets users contact the site administration. Personal contact forms allow users to contact one another by e-mail. Users can specify a subject and message, and also request that a copy of their e-mail be sent to their own address.') .'</p>';

"post" here, though we are using it differently, may be confusing given how we most often use "posts" as content. Perhaps "provide".

And, not to muddy the water, but the Contact us form can actually be used for a number of purposes depending on the category, as in the original example of directing "website feedback" to site administrators, but "product information" to a sales team.

Edit: I left out a word or three in the sentence above.

Here's another run at it based on the past couple of posts.

+      $output = '<p>'. t('The contact module provides a <em>Contact us</em> form and also gives each user a personal contact form, for easy communication. The <em>Contact us</em> form lets users contact admin defined recipients, (these can be grouped in one or more categories, for example "site administrators", "sales team"). Personal contact forms allow users to contact one another by e-mail. Users can specify a subject and message, and also request that a copy of their e-mail be sent to their own address.') .'</p>';

It might be back towards muddying the waters again. This is a tricky one to get right :(

Thanks O Govinda. I had never looked at the handbook page for contact module, and its text was very helpful.

I've tweaked it a good bit to be more in line with what is typically found in other module help texts, and attached a patch for review. I'm sure it isn't perfect, but I think it covers most of the bases, while making a distinction between personal contact forms and THE contact page.

One more time, to fix an indentation issue in the prior patch.

Rerolling after change in help text "For more information" line.

changed a single quoted string with backlash to double quotes. Text looks great!

er, and another one.

O Govinda, we definitely need an upgrade path for the permission. I don't have time to look at this today, but will try to get on it the next couple of days if Keith doesn't beat me to it.

Eeeek, I would not like to have a permission change so late :| Contrib modules might build on permission names and we are so much into the release cycle.

@O Govinda,

Thank you for your thoughtful and lengthy reply. You point out some valid concerns with the latest patch, and I've attempted to correct them as far as I am able.

In particular, you note that the new patch has "quite a few problems with grammar, syntax, and overuse of passive voice". No doubt, it was certainly passive; after rereading it, I quite agree with you. Perhaps this new patch will be a bit more active voice. If you have an opportunity to review it, that would be great.

You also write:

The last section of text added in the patch still has "side-wide contact form."

I absolutely believe you that this is the case, however, I'm not sure I saw the exact place you mention. site-wide contact form is in the permission, but surely that isn't what you are referring to? In any event, again, I just did a search for "site-wide" (found it in the permission) and found no instances of "site wide" or "sitewide" in the new patch. No doubt I'm missing it somewhere, though.

In paragraph 3, last line, will the relevant permission still be called "access site-wide contact form"? Seems like the names for the two permissions on the permissions page deserve to be updated.

Very valid point, although I'm not certain how much time we have available for this. It is likely out of scope for this issue, in any case.

In paragraph 4, I think "navigation menu settings page" should be "navigation menu administration page." (Some modules have distinct "settings" pages, marked "Settings.")

I just left this part out of the new patch; surely people will know how to enable menu items (hopefully).

In paragraph 5, the link for contact form settings page needs to go one level deeper. (Should be: ?q=admin/build/contact/settings.)

Thank you for catching this -- I had this pointing to the wrong link, and it should be corrected in the current patch.

I would suggest, as far as possible, using the handbook text as is, just renaming pages where needed, rearranging sections if need be, and subtracting sections not in line with the help texts for other modules.

I took your text from #32, above, pasting it into the appropriate place in contact.module, and went to admin/help/contact so that I could read through it. That text, and the text on the handbook page is fine, and has arguably better grammar and syntax than this patch. I see that in December and January last, you edited the contact handbook page (and that is much appreciated!) and the text you propose borrows in large part from that.

As I say, I started from there, and edited to account for:

• My feeling that the first sentence was misleading in that it suggested the only use for the contact page was to contact the "people running your site."
• I feel that the contact form is distinct enough from personal contact form without renaming it to Contact us, or whatever. Site-wide contact form was clunky though, and like you, I'm glad to be largely rid of that.
• A great number of non-developers who read Privileged users such as site administrators... will misinterpret that sentence (or at least have to read it twice).
• As you mention, many of the menu options, field descriptions, and other bits and pieces on the interface have been renamed and no longer fit that text. This is not a criticism -- simply that documentation is static until changed, and the world often shifts around it.

But yes, the text you propose is fine, as long as these items are addressed. The patch in #33 was what I came up with to do that, and it largely drew on your suggestions. This is, thankfully, an iterative process.

But I leave the matter up to you.

There we disagree. I am a citizen in a meritocracy (led by a benevolent dictator and his trusted lieutenants). The extent to which this matter is up to me is proportional to my ability to present good ideas (backed up with well-formed patches or other contributions) accompanied with well-reasoned arguments. This issue is just as much up to you. :)

I don't know how much more I can help. My web access this month is limited. (I'm in the Indian countryside, borrowing a connection that's slow and costly.)

Though, of course, I understand the constraints you are working under. That you've given this issue the attention you have with a less than ideal connection to the 'Net is even more notable.

@catch: I had to move some double quotes back to single to account for some possessives and some a href links in the same string. Thanks for those rerolls yesterday.

@all: Oh please, lets debate the permission change in a new issue.

Edit: after all that, I forgot to attach the file.

Committed this one, thanks. It is unfortunately too late to modify permissions at this stage.