Page MenuHomePhabricator

Document how to add a new Notification type created by an extension to the Help pages
Closed, ResolvedPublic

Description

Based on T110604#2515527

Necessary things are:

  • Notification name
  • A screenshot
  • which kind of notification it is (notice or alert)
  • what triggers that notification
  • what is received by user:
    • Primary information (first link)
    • Secondary information (second link)
    • Details (what's at the bottom of that notification

You can find inspiration in https://www.mediawiki.org/wiki/Help:Notifications/Notifications_types

Integration:

  • If that new notification is used on all WMF wikis as a "core" extension (like "Thanks" extension is), it can be integrated in the Default notifications section.
  • If that new notification is used on some WMF wikis as an optional extension or Beta feature, it can be integrated in the Notifications from optional extensions section.
    • If an extension tested as a Beta feature or active only on certain wikis changes something on a Default notifications, it can be documented on the Default notifications section, as a separated paragraph, with all necessary details.
  • If that new notification is not used on WMF wikis, it has to be on a separate page, with all user documentation for the extension to avoid. A link can be created from the notifications type page to that documentation.

When to do that
It is possible to do that before merging the task. In that case, please follow some recommandations:

All this is open to comments. I'll then create an Help page on mw.org.

Event Timeline

Restricted Application added a project: Collaboration-Team-Triage. · View Herald TranscriptAug 2 2016, 3:37 PM
Zppix added a subscriber: Zppix.Aug 2 2016, 3:40 PM

@Trizek-WMF I can help create and copyedit the help page if need be as well.

@Trizek-WMF I can help create and copyedit the help page if need be as well.

Cool! I'll ping you when I'll integrate all of this, probably next week. :)
Do you see any blocking or strange things in what I've written in that task's description so far?

Trizek-WMF moved this task from Backlog to External on the Notifications board.Aug 2 2016, 3:42 PM
Trizek-WMF moved this task from External to In progress on the Notifications board.

If that new notification is used on all WMF wikis as a "core" extension (like "Thanks" extension is), it can be integrated in the Default notifications section.

In other words, it is provided from the Echo extension... which Thanks is not. So Thanks actually belongs to optional extensions.

jmatazzoni added a comment.EditedAug 2 2016, 8:10 PM

@Trizek-WMF, What is Collaboration Team's oversight responsibility when people are creating new notification types? I ask because if we need to be involved—if we need to review the format, links, etc. to ensure they meet style—then I have some thoughts about the type of documentation needed to ensure that people account for all the possible variations and to make reviewing more straightforward. I'm thinking in terms of a form that will lead them through the process.

If that new notification is used on all WMF wikis as a "core" extension (like "Thanks" extension is), it can be integrated in the Default notifications section.

In other words, it is provided from the Echo extension... which Thanks is not. So Thanks actually belongs to optional extensions.

Thanks is integrated to all wikis and is provided by default (but can be opt-out). That's why it is on the Default notifications section.
At the opposite, Flow is not integrated to all wikis and is in the optional section.

@Trizek-WMF, What is Collaboration Team's oversight responsibility when people are creating new notification types? I ask because if we need to be involved—if we need to review the format, links, etc. to ensure they meet style—then I have some thoughts about the type of documentation needed to ensure that people account for all the possible variations and to make reviewing more straightforward. I'm thinking in terms of a form that will lead them through the process.

This should be documented as part of Extension:Echo, I think: T116612: Document new Echo formatting system T136372: Document how to create a new notification type

@Trizek-WMF Below please find my effort at creating a "form" that can be used in Phabricator so that people can supply the information necessary to create a new notification. It's intended to guide people on all the points they need to think through. It will also help us review people's ideas and QA them when the time comes.

For clarity, I added a filled-in version of the form below the empty one. Including such an example is probably a good idea, so people can see what we're looking for.

Finally, it's necessary to put virtually all of the items inside the brackets here onto the glossary you're creating. You could literally make each of these bracketed items a link. Clicking on these links would explain, for example, what the difference is between the header and the body, or what would determine whether a message should be bundled or not.

BASIC INFORMATION

  • [notification name] :
  • [what triggers notification?] :
  • ["Notice" or "Alert"?] :
  • [will this be a bundled notification?] :

WORDING

[single message]

  • [header] :
  • [body] :

[Bundled Messages]

  • [main, bundling message] :
  • [subsidiary, bundled message] :

LINKS

  • [primary link target] :
  • [primary link label] :
  • [#1 secondary link target :
  • [#1 secondary link label] :
  • [#2 secondary link target] :
  • [#2 secondary link label] :

[ICON--See list of existing icons]

  • [icon name] :

[EXAMPLE OF FILLED OUT FORM]

BASIC INFORMATION

  • [notification name] : flow-post-reply
  • [what triggers notification?]] : someone posts in a Flow topic you are watching
  • ["Notice" or "Alert"?]] : Notice
  • [will this be a bundled notification?]] : yes

WORDING

[single message]

  • [header] : Username replied in "Topicname".
  • [body] : Excerpt of the message.

[Bundled Messages]

  • [main, bundling message] : 5 new replies in "Topicname".
  • [subsidiary, bundled message] : Username: "Excerpt of the message..."

LINKS

  • [primary link target] : The "reply" (i.e. the new post)]
  • [primary link label] : View message
  • [#1 secondary link target] : the user page of the user who did the action
  • [#1 secondary link label] : the username of the user who did the action
  • [#2 secondary link target] : null
  • [#2 secondary link label] : null

[ICON--See list of existing icons]

  • [icon name] : User talk
Trizek-WMF added a comment.EditedAug 26 2016, 3:45 PM

Thanks Joe.

I may review the documentation to add icons to it. Or add them to the glossary?

Note about forms on Phabricator: here is the doc.

Trizek-WMF updated the task description. (Show Details)Sep 28 2016, 2:25 PM
Trizek-WMF raised the priority of this task from Normal to High.Sep 29 2016, 8:30 AM

Last call before marking that task as Resolved.

Trizek-WMF closed this task as Resolved.Oct 13 2016, 2:28 PM