Page MenuHomePhabricator

Update mention sending information
Closed, DuplicatePublic8 Story Points

Description

Task: The Manual:Echo page [1] intends to give a complete list of when mention are being sent out. This list should be updates according to our learnings + changes and be as understandable as possible.
Please update the link, taking into account

[] T136323: Investigate cases where no mention happens due edit instead of addition

Furthermore, we should mention the new notifications (but on which page?)

[1]: https://www.mediawiki.org/wiki/Manual:Echo

Event Timeline

Lea_WMDE created this task.Jun 29 2016, 8:58 AM
Restricted Application added subscribers: Zppix, Aklapper. · View Herald TranscriptJun 29 2016, 8:58 AM
Tobi_WMDE_SW set the point value for this task to 13.Jun 29 2016, 12:30 PM
Tobi_WMDE_SW moved this task from Proposed to Backlog on the TCB-Team-Sprint-2016-06-29 board.

https://www.mediawiki.org/wiki/Help:Notifications should also be updated and has the advantage of being translatable.

We probably shouldn't add each part until it has actually been merged!

WMDE-leszek moved this task from Backlog to Doing on the TCB-Team-Sprint-2016-06-29 board.

TL;DR: I've put a draft of the expanded Mention Notifications description in https://www.mediawiki.org/wiki/User:Leszek_Manicki_(WMDE)/Help:Notifications/Notification_types#Mentions

I've copied over current version of Manual:Echo to https://www.mediawiki.org/wiki/User:Leszek_Manicki_(WMDE)/Echo and updated links to specific places in code (ie. line numbers). I've also expanded it a bit.

That said I am not really convinced it actually makes sense to improve this particular page. It seems to serve as a kind of guide to end users (what to do to ping a user) but on the other hand it provides quite detailed low-level description (other's signatures cannot be present in the message, what section levels are allowed, how variables are expanded, how to link to a user etc) with all those links to particular lines of Echo's code.
I believe a bit more general description including information what steps to take in order to ping a user should be enough for (most) users. This kind of help has already been provided in https://www.mediawiki.org/wiki/Help:Notifications/Notifications_types#Mentions.
I've copied this page over to https://www.mediawiki.org/wiki/User:Leszek_Manicki_(WMDE)/Help:Notifications/Notification_types#Mentions and started to expand it. All comments and edits are welcome.

And as far as referring to the code is concerned I don't think putting this on wiki page is really useful. Every time the code changes it is potentially needed to update the page, even if the change is completely non-functional (ie. adding a comment somewhere above relevant lines). Otherwise references are out of sync and might not be very helpful. I think it would rather be useful to invest some time to improve the in-code documentation (e.g. by improving tests which will also show what usage is allowed and what is not, and adding comments where it makes sense).

Similar concerns have been IMO already raised in https://www.mediawiki.org/wiki/Manual_talk:Echo. I believe in order to be actually useful Manual:Echo should be completely re-created. OTOH I am not really sure what this page should include. General "technical" issues related to the extension itself are on Extension:Echo page.

My understanding of what the background of this ticket is that there has been some amount of confusion among the users, why some "mentions" don't get sent, and how does on actually do those mentions properly. I believe clarifying such issues could be pretty much achieved by expanding Help:Notifications. If there are some more detailed issues with some special cases not covered by the (soon-to=be=improved) help, those could be discussed on the help's discussion page. Some general "Mentions problems" subpage could be also created somewhere (not sure if as a subpage of the Help:Notifications, though) but right now it is not really clear to me if it is really needed.

And I entirely agree with @Addshore that "mentioning self" and "easy mention failure notifications" should only be reflected in the help/manual page (be it whatever page in the end) once the features are implemented (ie. merged)! There is clearly some work left to be done with this ticket but documenting new features should not block closing the ticket IMO.

To sum up: At this point a reasonable way forward would be for me to expand Mentions sections of the Help:Notifications subpage, and working with interested people on either completely rebuilding or removing Manual:Echo.

If referring to the code is really needed/expected we could have those references more "reliable" by making references to a line in a particular version (ie. git commit). But this still seems not that nice to me.

WMDE-Fisch changed the point value for this task from 13 to 8.

Some progress has been made

WMDE-leszek triaged this task as Normal priority.Aug 10 2016, 12:03 PM