Better Description on Publishing Options, please...

I think you refer to og_subscriptions. og does not say this.

@MGParisi, the text you refer is defined at line 538 of subscriptions_content.module file, which is part of Subscriptions Module. This is much a support request so I'm moving this issue to corresponding queue.

Blessings!

What it's saying is that if you're just promoting the node to the front page, then you probably shouldn't let all the subscribers know.

Basically the whole description is stating the obvious, it should be removed to save confusion.

@MGParisi: Rowanw is right. Your omission of the italic style has not made it easier to understand, so let me quote it again as it appears in the Publishing options fieldset:

You may want to turn this OFF if you only change Promoted to front page or Sticky at top of lists, otherwise Subscriptions will send out "update" notifications.
Subscriptions does not send notifications for unpublished nodes (except to users who have the administer nodes permission), but when you set Published to ON, Subscriptions will send out "new" notifications, unless you turn this off here.

If you still don't understand it, then let me know and I'll try to explain it in detail.

It is indeed stating the obvious, but sometimes it's useful to have some reassurance that a piece of software really does behave as it should. That's why I put this text there, and I still think it does more good than harm, but (once you understand its meaning) please tell me how it should be worded so that you would understand it from the start.

Salvis, I disagree. There's a higher-than-average amount of text in the Subscriptions module and it's a big concern to me, or maybe it's just the red text that concerns me.

Anyway, the paragraph in question is a good example of superfluous text that we could do without. I mean we might as well add warnings for each of those publishing checkboxes, for example, "Do NOT publish this page if it's not ready for public viewing". It's entirely possible to intimidate a user by putting too much text in front of them.

Argh, I tried to show the text with the italics that the OP had removed, but everything came out in italics. So, again:

————
You may want to turn this OFF if you only change Promoted to front page or Sticky at top of lists, otherwise Subscriptions will send out "update" notifications.
Subscriptions does not send notifications for unpublished nodes (except to users who have the administer nodes permission), but when you set Published to ON, Subscriptions will send out "new" notifications, unless you turn this off here.
————

@MGParisi: There's no reason to apologize. I welcome every issue post and take it as an opportunity to tune things so that this post will not be necessary in the future.

Now let me try to explain:

1. Out of the box, Subscriptions sends out notifications only for newly created posts; I call these "new" notifications.
2. "New" notifications are sent only for published posts, with one exception: users with the administer nodes permission will receive "new" notifications also for unpublished posts.
   In other words: users get "new" notifications for those posts that they can see. Users do not get "new" notifications for posts that they cannot see, because they are unpublished.
3. When the admin changes the status of a post from unpublished to published, then "new" notifications are also sent. This is because at that point the post becomes visible to normal users.
4. The admin can enable subscribing to updates of a node. If a user subscribes to updates, they also get a notification when the node is updated; I call these "update" notifications.
5. If the admin changes Promoted to front page or Sticky at top of lists, then this counts as an update and "update" notifications are sent out.
6. This latter behavior is usually undesired, because the users have already received "new" notifications, and they don't care about the state of Promoted to front page and Sticky at top of lists. This is the reason for introducing the Send subscriptions notifications checkbox.
   The first sentence tries to say: If you change only Promoted to front page or Sticky at top of lists, then watch out: Subscriptions will send out "update" notifications! If you want to avoid this, you should activate the Send subscriptions notifications checkbox also.
7. The statement "Subscriptions will send out 'update' notifications!" above is not completely true, so I had to add "Subscriptions does not send notifications for unpublished nodes."
8. The statement "Subscriptions does not send notifications for unpublished nodes" above is not completely true either, so I had to add "(except to users who have the administer nodes permission)."
9. So what happens with unpublished nodes? Another addition: "when you set Published to ON, Subscriptions will send out "new" notifications."
10. And the last bit: you can use the Send subscriptions notifications checkbox to suppress the sending of "new" notifications in this case.
    This sums up the second sentence.

I find it very difficult to write without commas. The behavior that I'm trying to describe is straight-forward and reasonable, but different cases and subcases need to be considered. I have made the experience that people complain, if I write something that is not 100% true. So I try to write the full truth, but people also complain when I write too much text.

I hope you can understand the items #1 through #10 above, but I admit that I have some doubts because I don't know what structures I can use. It's impossible to break down a complex situation into simple affirmative statements. — This would probably work a lot better if we could talk face to face, but in writing I find it very challenging.

@Rowanw: As you can see above, describing "reasonable" behavior in detail can be challenging. Of course I can't put #1 through #10 into the Publishing options fieldset, but not everyone agrees what "reasonable" behavior means. Some users insist on forming a precise picture of how Subscriptions behaves. Even though it may be obvious to you and me, it's not so for everyone. I'm trying very hard to provide just the exact amount of information to maximize the number of those who form the right picture and to minimize the number of those who form a wrong picture.

@Rowanw: Regarding the red text: I didn't have that until recently, but I found out that people were confused, because admin/settings/subscriptions/userdefaults and user/UID/subscriptions look the same (depending on the settings of the former).

Salvis, after reading your list I actually learnt a few things I didn't know about earlier, I take my comment back about it being "obvious".

Why not introduce some PHP logic to deliver only the relevant information?

For instance, if the node is not published:

[ ] Send subscriptions notifications
Send a notification when this post is published.

If the node is published:

[ ] Send subscriptions notifications
Send a notification when the promoted or sticky options are changed.

@Rowanw: You are oversimplifying, too.

For instance, if the node is not published:

[ ] Send subscriptions notifications
Send a notification when this post is published.

Users who can see unpublished posts will get notifications whether it's published or not. IOW, this is not strictly true.

BTW, it's ON by default.

If the node is published:

[ ] Send subscriptions notifications
Send a notification when the promoted or sticky options are changed.

Avoiding notifications when changing promoted or sticky are the most common uses of this, but it's neither limited to those uses nor dependent on the state or transition of any of the three flags.

I wish I could have simply checked whether the user changes nothing but sticky and/or promoted (and suppress the notification automatically), but unfortunately this is difficult. For example, the node could be event-enabled, so Subscriptions would need to also check whether the event date/times have changed or not. As it is, it's a general mechanism, but users may not realize that changing sticky/promoted would trigger update notifications in the first place, so I do want to mention them specifically.

The way you worded points 5 and 6 sounded like it was only sticky and promoted that triggered the notifications.

"Users who can see unpublished posts will get notifications whether it's published or not. IOW, this is not strictly true."

Yeah, but the user shouldn't be concerned about moderators getting updates, it isn't nearly as important as the other info in my opinion.

Take 2 - for an already published node.

[ ] Send subscriptions notifications
Send a notification if there is something new for subscribers to know about.

Simple and broad, yet accurate. ;)

Yeah, but the user shouldn't be concerned about moderators getting updates, it isn't nearly as important as the other info in my opinion.

A site may use Subscriptions as a moderator-only tool. I get bug reports if unexpected notifications are sent out.

[ ] Send subscriptions notifications
Send a notification if there is something new for subscribers to know about.

This is unclear. You probably mean that the poster should leave this active if he considers that "there is something new for subscribers to know about". It could just as well be interpreted as activating some kind of artificial intelligence that will send notifications ONLY "if there is something new for subscribers to know about".

And it fails to make the user think about whether changes to promoted/sticky are changes that should be notified.

And it's unclear whether this is supposed to override Published or not.